@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/CookbookTestUtils.js

@@ -3,7 +3,7 @@
 const {
   MIN_COOKBOOK_FORMAT_VERSION,
   checkCookbookFormatVersion,
-  normalizeCookbookSteps,
+  readCookbookSteps,
   stepIdentityOf
 } = require('./utils/cookbookFormat');
 
@@ -85,13 +85,12 @@ class CookbookTestUtils {
       errors.push(versionProblem);
     }
 
-    // Both documented shapes, through the one owner of that rule. Requiring an
-    // array here rejected every V2 object-shaped cookbook, and requiring `id`
-    // rejected every cookbook that follows format.md — measured 2026-08-30,
-    // that was 100 % of the tree.
+    // The one shape the format allows, through the one owner of that rule
+    // (`utils/cookbookFormat`), so this entry point and the Tier-1 runner cannot
+    // disagree about what a cookbook's steps are.
     let steps;
     try {
-      steps = normalizeCookbookSteps(cookbook.steps);
+      steps = readCookbookSteps(cookbook.steps);
     } catch (error) {
       // The refusal is the finding. This entry point answers with a list, not
       // an exception, so the message becomes one more error in that list.
@@ -137,8 +136,8 @@ class CookbookTestUtils {
     }
 
     // Compare steps
-    const steps1 = normalizeCookbookSteps(cookbook1.steps);
-    const steps2 = normalizeCookbookSteps(cookbook2.steps);
+    const steps1 = readCookbookSteps(cookbook1.steps);
+    const steps2 = readCookbookSteps(cookbook2.steps);
 
     if (steps1.length !== steps2.length) {
       differences.push({

package/src/ServiceReadinessValidator.js

@@ -1,10 +1,8 @@
 'use strict';
 
+const { assertLogger } = require('@onlineapps/logger-contract');
 const CookbookTestUtils = require('./CookbookTestUtils');
-
-// The logger methods this validator requires — the order is the order the
-// error message lists them in.
-const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+const { HANDLER_REF_PATTERN } = require('./utils/handlerRef');
 
 /**
  * The semver 2.0.0 grammar, verbatim from semver.org's own published regular
@@ -38,16 +36,9 @@ const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]
  * previously spent on `health` fold into `operations` so total stays
  * at 100.
  *
- * 2026-08-22: the `url` the probe consumed is gone too. It outlived the
- * probe by five months as an accepted-and-ignored argument echoed into
- * `results.serviceUrl` and printed as a `URL:` line — a report field
- * naming an endpoint that does not exist. The only caller that still
- * passed one was Tier-1's readiness step, and that step is gone
- * (see ValidationOrchestrator: its verdict was a strict function of
- * steps 2 and 3). What is left has exactly one consumer:
- * `helpers/createServiceReadinessTests`, and through it the
- * `tests/bootstrap/` suites of the biz repos — which pass name, version,
- * operations, testCookbook and registry, and never passed a url.
+ * `validateReadiness(service)` reads `name`, `version`, `operations`,
+ * `testCookbook` and `registry`. Those five are what it reads, and it
+ * reads no others.
  *
  * @see api/docs/biz/30-operations/schema-v3.md
  * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (input probe contract)
@@ -61,26 +52,11 @@ class ServiceReadinessValidator {
     // caller that did not print the returned object learned nothing about why a
     // service was refused. Owner confirmation:
     // docs/governance/confirmations/connector-logger-contract.md 001.
-    if (!options.logger) {
-      throw new Error(
-        '[ServiceReadinessValidator] Logger is required - Expected: a logger with info/warn/error/debug, '
-        + 'so the readiness verdict leaves the process. '
-        + 'Fix: pass options.logger (e.g. the logger your service already built).'
-      );
-    }
-
-    const missingLoggerMethods = LOGGER_METHODS.filter(
-      (method) => typeof options.logger[method] !== 'function'
+    this.logger = assertLogger(
+      'ServiceReadinessValidator',
+      options.logger,
+      'the readiness verdict leaves the process'
     );
-    if (missingLoggerMethods.length > 0) {
-      throw new Error(
-        '[ServiceReadinessValidator] Logger is incomplete - Expected: info, warn, error, debug as functions; '
-        + `missing: ${missingLoggerMethods.join(', ')}. `
-        + 'Fix: pass a logger implementing all four.'
-      );
-    }
-
-    this.logger = options.logger;
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
     // Core checks ALWAYS run, optional checks run if testCookbook/registry provided
@@ -253,7 +229,6 @@ class ServiceReadinessValidator {
       }
 
       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 [name, operation] of Object.entries(operations)) {
@@ -262,7 +237,7 @@ class ServiceReadinessValidator {
         }
         if (!operation.handler) {
           errors.push(`Operation '${name}' missing handler (v3 — 'handlers/<path>#<export>')`);
-        } else if (!handlerPattern.test(operation.handler)) {
+        } else if (!HANDLER_REF_PATTERN.test(operation.handler)) {
           errors.push(`Operation '${name}' has invalid handler ref: '${operation.handler}'`);
         }
         if (!operation.bundle_scope) {

package/src/ValidationOrchestrator.js

@@ -15,16 +15,34 @@ const FingerprintUtils = require('@onlineapps/service-validator-core').Fingerpri
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
 const CookbookTestRunner = require('./CookbookTestRunner');
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { HANDLER_REF_PATTERN } = require('./utils/handlerRef');
+const { loadManifest, DEFAULT_MANIFEST_PATH } = require('./manifest/loadManifest');
+const { runManifest } = require('./manifest/runManifest');
+const { resolveWorkspaceRoot } = require('./manifest/workspaceRoot');
+const { renderBanner, describeFinding } = require('./manifest/report');
+const { buildDeployabilitySignal, writeDeployabilitySignal } = require('./manifest/deployabilitySignal');
 
-// The logger methods this orchestrator requires — the order is the order the
-// error message lists them in.
-const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+/**
+ * The manifest rows step 2 answers: the configuration documents a biz service is
+ * configured by. Named here once, and the ONLY place the split between step 2
+ * and step 7 is stated.
+ *
+ * Step 2 used to check `config.json`/`service.name` and `operations.json` with
+ * hand-written sentences of its own, while these rows demand the same documents
+ * with more coverage, an owner, a fix and a doc pointer — and reported the same
+ * defect a second time in step 7. One concern, one rail
+ * (`.claude/rules/change-discipline.md`); the step keeps its PLACE in the boot
+ * order, because steps 3-6 must not run behind a broken configuration and step 7
+ * runs after them.
+ */
+const CONFIG_STEP_ROWS = Object.freeze(['C-SERVICE', 'C-OPS', 'C-CONTRACT']);
 
 /**
  * ValidationOrchestrator
  *
  * Orchestrates complete service validation (Tier 1 Pre-Validation)
- * Runs a 6-step validation process and generates validation proof.
+ * Runs a 7-step validation process and generates validation proof.
  *
  * Called automatically by ServiceWrapper during initialization.
  *
@@ -34,12 +52,8 @@ const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
  * 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.
+ * Constructor options: `serviceRoot`, `serviceName`, `serviceVersion`, `logger`.
+ * Those four are what it reads, and it reads no others.
  */
 class ValidationOrchestrator {
   constructor(options = {}) {
@@ -52,26 +66,11 @@ class ValidationOrchestrator {
     // An incomplete logger therefore reached the runner one line later and threw
     // in its name instead of this one. Owner confirmation:
     // docs/governance/confirmations/connector-logger-contract.md 001.
-    if (!options.logger) {
-      throw new Error(
-        '[ValidationOrchestrator] Logger is required - Expected: a logger with info/warn/error/debug, '
-        + 'so validation narrates where the service writes. '
-        + 'Fix: pass options.logger (e.g. the logger your service already built).'
-      );
-    }
-
-    const missingLoggerMethods = LOGGER_METHODS.filter(
-      (method) => typeof options.logger[method] !== 'function'
+    this.logger = assertLogger(
+      'ValidationOrchestrator',
+      options.logger,
+      'validation narrates where the service writes'
     );
-    if (missingLoggerMethods.length > 0) {
-      throw new Error(
-        '[ValidationOrchestrator] Logger is incomplete - Expected: info, warn, error, debug as functions; '
-        + `missing: ${missingLoggerMethods.join(', ')}. `
-        + 'Fix: pass a logger implementing all four.'
-      );
-    }
-
-    this.logger = options.logger;
 
     // config/service/ is the ONLY configuration path (owner decision
     // 2026-09-03). The legacy conn-config/ branch is gone: zero such
@@ -83,6 +82,12 @@ class ValidationOrchestrator {
     this.runtimePath = path.join(this.serviceRoot, 'conn-runtime');
     this.proofPath = path.join(this.runtimePath, 'validation-proof.json');
 
+    // The manifest run of THIS validation, computed on first use (manifestRun()).
+    // One orchestrator is one run: `ServiceWrapper._createValidationOrchestrator()`
+    // builds a fresh one for every attempt, including the revalidation path, so a
+    // value cached here is never handed to a second measurement of the tree.
+    this._manifestRun = null;
+
     // Validators
     this.structureValidator = new ServiceStructureValidator(this.serviceRoot);
     this.cookbookRunner = new CookbookTestRunner({
@@ -192,7 +197,8 @@ class ValidationOrchestrator {
       const envTemplateFile = path.join(this.serviceRoot, '..', '..', 'config', 'env-templates', `${path.basename(this.serviceRoot)}.env`);
 
       if (!fs.existsSync(configFile)) {
-        throw new Error('config.json not found');
+        throw new Error(`[ValidationOrchestrator] config.json not found - Expected the service `
+          + `configuration at ${configFile}, which the fingerprint hashes. Fix: create that file.`);
       }
 
       const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
@@ -272,14 +278,20 @@ class ValidationOrchestrator {
 
       return FingerprintUtils.generate(fingerprintData);
     } catch (error) {
-      throw new Error(`Failed to calculate fingerprint: ${error.message}`);
+      throw new Error('[ValidationOrchestrator] Failed to calculate the service fingerprint - Expected '
+        + 'config/service and the infra files to be readable and valid JSON. Fix: repair whatever the '
+        + `cause names (${error.message})`,
+      { cause: error });
     }
   }
 
   /**
-   * Run the full 6-step validation process.
+   * Run the full 7-step validation process. Step 7 joined the six below when the
+   * uniform manifest landed (confirmation `biz-service-manifest` 001 §3.1); it is
+   * the only step whose findings can leave the run successful and the service
+   * undeployable.
    *
-   * There were six steps until 2026-08-22. Step 5, "Service Readiness",
+   * There was a different sixth step 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:
@@ -321,12 +333,19 @@ class ValidationOrchestrator {
       warnings: [],
       totalTests: 0,
       passedTests: 0,
-      failedTests: 0
+      failedTests: 0,
+      // Step 7 fills these. `null` is not "deployable": it says the run stopped
+      // at a fail-fast step before conformance was measured, and a consumer
+      // that cannot tell those apart would read an unmeasured tree as a clean
+      // one (confirmation biz-service-manifest 001 §4).
+      deployable: null,
+      deployFindings: [],
+      notRun: []
     };
 
     try {
       // Step 1: Service Structure
-      this.logger.info('[ValidationOrchestrator] Step 1/6: Service Structure');
+      this.logger.info('[ValidationOrchestrator] Step 1/7: Service Structure');
       results.steps.structure = await this.validateStructure();
       if (!results.steps.structure.valid) {
         results.success = false;
@@ -336,7 +355,7 @@ class ValidationOrchestrator {
       }
 
       // Step 2: Config Files
-      this.logger.info('[ValidationOrchestrator] Step 2/6: Config Files');
+      this.logger.info('[ValidationOrchestrator] Step 2/7: Config Files');
       results.steps.config = await this.validateConfig();
       if (!results.steps.config.valid) {
         results.success = false;
@@ -350,7 +369,7 @@ 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/6: Environment Contract');
+      this.logger.info('[ValidationOrchestrator] Step 3/7: Environment Contract');
       results.steps.env = this.validateEnvContract();
       if (!results.steps.env.valid) {
         results.success = false;
@@ -361,7 +380,7 @@ class ValidationOrchestrator {
       }
 
       // Step 4: Operations Compliance
-      this.logger.info('[ValidationOrchestrator] Step 4/6: 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) {
@@ -370,7 +389,7 @@ class ValidationOrchestrator {
       }
 
       // Step 5: Cookbook Tests
-      this.logger.info('[ValidationOrchestrator] Step 5/6: 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;
@@ -381,7 +400,7 @@ class ValidationOrchestrator {
       }
 
       // Step 6: Connector Integration
-      this.logger.info('[ValidationOrchestrator] Step 6/6: Connector Integration');
+      this.logger.info('[ValidationOrchestrator] Step 6/7: Connector Integration');
       results.steps.connectors = this.validateConnectors();
       if (!results.steps.connectors.valid) {
         // Severity is unchanged: the connector contract stays non-critical and
@@ -397,6 +416,27 @@ class ValidationOrchestrator {
         results.warnings.push(...results.steps.connectors.errors);
       }
 
+      // Step 7: Manifest conformance
+      //
+      // The uniform of a biz service, measured against the manifest that ships
+      // inside this package — so the service's pin decides which shape it is
+      // measured against (confirmation biz-service-manifest 004 point 2).
+      //
+      // Two severities, two consequences (001 §4): a `boot` finding fails the
+      // validation like every other step above, while a `deploy` finding leaves
+      // 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) {
+        results.success = false;
+        results.errors.push(...results.steps.manifest.errors);
+      }
+
       // Finalize and generate proof if successful
       return await this.finalizeResults(results, startTime);
 
@@ -426,46 +466,63 @@ class ValidationOrchestrator {
   }
 
   /**
-   * Step 2: Validate config files
+   * Step 2: the configuration documents, as the manifest rows CONFIG_STEP_ROWS
+   * demand them.
+   *
+   * The step decides nothing of its own: it runs the manifest (once per
+   * validation — manifestRun() below) and reports the findings of those three
+   * rows, each with the id, the owner and the fix its row carries. Step 7 then
+   * leaves them out, because they are answered, not because they stopped
+   * mattering.
+   *
+   * Which severity fails the boot is the uniform's own list, never a constant
+   * here — a service raises `boot`, a library `publish` (`api/shared/TODO.md`
+   * §0.2b-15).
+   *
+   * @returns {{valid: boolean, errors: string[], findings: object[]}}
    */
   async validateConfig() {
-    const errors = [];
-
     try {
-      // Validate config.json
-      const configFile = path.join(this.configPath, 'config.json');
-      if (!fs.existsSync(configFile)) {
-        errors.push('config.json not found');
-      } else {
-        const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-        if (!config.service?.name) errors.push('config.json missing service.name');
-        // Note: service.version is now read from package.json (Single Source of Truth)
-      }
+      const run = this.manifestRun();
+      const findings = run.findings.filter((finding) => CONFIG_STEP_ROWS.includes(finding.id));
+      const blocking = findings.filter((finding) => run.blockingSeverities.includes(finding.severity));
 
-      // Validate operations.json
-      const operationsFile = path.join(this.configPath, 'operations.json');
-      if (!fs.existsSync(operationsFile)) {
-        errors.push('operations.json not found');
-      } else {
-        const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
-        if (!operations.operations || Object.keys(operations.operations).length === 0) {
-          errors.push('operations.json has no operations defined');
-        }
-      }
-
-      this.logger.info(`[ValidationOrchestrator] ✓ Config files: ${errors.length === 0 ? 'PASS' : 'FAIL'}`);
+      this.logger.info(`[ValidationOrchestrator] ✓ Config files: ${blocking.length === 0 ? 'PASS' : 'FAIL'}`);
       return {
-        valid: errors.length === 0,
-        errors: errors
+        valid: blocking.length === 0,
+        errors: blocking.map(describeFinding),
+        findings
       };
     } catch (error) {
+      // A broken manifest or an unreadable service root fails this step by its
+      // own name, the way step 7 does — never as "no findings".
+      this.logger.error(`[ValidationOrchestrator] Step 2/7 could not run: ${error.message}`);
       return {
         valid: false,
-        errors: [`Config validation failed: ${error.message}`]
+        errors: [error.message],
+        findings: []
       };
     }
   }
 
+  /**
+   * The manifest run of this validation, computed once.
+   *
+   * Two steps read it — step 2 the configuration rows, step 7 every other row —
+   * and running the manifest twice would walk the repository twice and, worse,
+   * could answer the two steps differently if the tree changed between them.
+   *
+   * @returns {object} the value `runManifest` returned
+   */
+  manifestRun() {
+    if (this._manifestRun === null) {
+      const workspaceRoot = resolveWorkspaceRoot({ startDir: this.serviceRoot });
+      const manifest = loadManifest(DEFAULT_MANIFEST_PATH);
+      this._manifestRun = runManifest({ manifest, serviceRoot: this.serviceRoot, workspaceRoot });
+    }
+    return this._manifestRun;
+  }
+
   /**
    * Step 3: Validate operations compliance (v3 — handler registry dispatch).
    * Required per operation: handler ('handlers/<path>#<export>'), bundle_scope, input, output.
@@ -482,7 +539,6 @@ class ValidationOrchestrator {
       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 || {})) {
@@ -492,7 +548,7 @@ class ValidationOrchestrator {
 
         if (!opDef.handler) {
           errors.push(`Operation ${opName}: missing handler (v3 — 'handlers/<path>#<export>')`);
-        } else if (!handlerPattern.test(opDef.handler)) {
+        } else if (!HANDLER_REF_PATTERN.test(opDef.handler)) {
           errors.push(`Operation ${opName}: invalid handler ref '${opDef.handler}' — expected 'handlers/<path>#<exportName>'`);
         }
 
@@ -549,13 +605,21 @@ class ValidationOrchestrator {
           total: 0,
           passed: 0,
           failed: 0,
+          cookbooks: { total: 0, passed: 0, failed: 0 },
           warnings: ['No cookbook tests found']
         };
       }
 
       const result = await this.cookbookRunner.runCookbooks(cookbooksPath);
 
-      this.logger.info(`[ValidationOrchestrator] ✓ Cookbook tests: ${result.passed}/${result.total} passed`);
+      // BOTH units, each named. The line used to read "Cookbook tests: X/Y"
+      // about STEP counts, so three one-step cookbooks reported "3/3" and the
+      // day one of them gained a second step the number rose with no cookbook
+      // added (BIZ-converter, 2026-08-27). A label that disagrees with its
+      // measurement is the false guarantee `automation-gates.md` §5 names.
+      this.logger.info(`[ValidationOrchestrator] ✓ Cookbooks: `
+        + `${result.cookbooks.passed}/${result.cookbooks.total} passed `
+        + `(${result.passed}/${result.total} steps)`);
 
       // `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
@@ -573,6 +637,7 @@ class ValidationOrchestrator {
         total: result.total,
         passed: result.passed,
         failed: result.failed,
+        cookbooks: result.cookbooks,
         errors: result.failed > 0 ? [`${result.failed} cookbook test(s) failed`, ...details] : []
       };
     } catch (error) {
@@ -581,6 +646,7 @@ class ValidationOrchestrator {
         total: 0,
         passed: 0,
         failed: 0,
+        cookbooks: { total: 0, passed: 0, failed: 0 },
         errors: [`Cookbook tests failed: ${error.message}`]
       };
     }
@@ -669,6 +735,85 @@ class ValidationOrchestrator {
     return { valid: result.valid, errors: result.errors };
   }
 
+  /**
+   * Step 7: Manifest conformance — the uniform of a biz service.
+   *
+   * Reads the service root this orchestrator was CONSTRUCTED with, never
+   * `process.cwd()`: the wrapper starts a service from wherever the container's
+   * entrypoint happens to stand, and a check that measured the current
+   * directory would silently measure the wrong tree.
+   *
+   * The workspace root is resolved upwards from that service root and is absent
+   * inside a container — the rows that need it are then reported NOT RUN, and
+   * 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.
+   *
+   * 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[],
+   *            deployFindings: object[], notRun: object[], signalPath: string|null}}
+   */
+  validateManifestConformance() {
+    try {
+      const result = this.manifestRun();
+
+      // 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
+      // log answered three of its rows one step earlier. What this step drops is
+      // only the second REPORT of those rows in its own table and errors.
+      for (const line of renderBanner(result)) {
+        this.logger.info(`[ValidationOrchestrator] ${line}`);
+      }
+
+      const signalPath = writeDeployabilitySignal({
+        serviceRoot: this.serviceRoot,
+        signal: buildDeployabilitySignal({
+          result,
+          validatorVersion: require('../package.json').version
+        })
+      });
+
+      const findings = result.findings.filter((finding) => !CONFIG_STEP_ROWS.includes(finding.id));
+      const bootFindings = findings.filter((finding) => finding.severity === 'boot');
+
+      return {
+        valid: bootFindings.length === 0,
+        deployable: result.ok,
+        errors: bootFindings.map(describeFinding),
+        findings,
+        // Read from the WHOLE run, for the same reason the banner and the signal
+        // are: `deployable` is a verdict about the tree, and these are the
+        // reasons behind it — not a second report of a row step 2 already
+        // showed. CONFIG_STEP_ROWS are declared `boot` today; the day the
+        // manifest gives one `deploy`, filtering here would print NOT DEPLOYABLE
+        // with nothing named as the cause (`automation-gates.md` §5).
+        deployFindings: result.findings.filter((finding) => finding.severity === 'deploy'),
+        notRun: result.notRun,
+        signalPath
+      };
+    } catch (error) {
+      // A broken manifest, an unreadable service root or an unwritable ci/ are
+      // contract violations, and they fail the validation like a `boot` finding
+      // — they are NOT reported as "no findings". They are returned rather than
+      // thrown so this step names itself, instead of surfacing as the generic
+      // "Validation error" of the catch in runFullValidation().
+      this.logger.error(`[ValidationOrchestrator] Step 7/7 could not run: ${error.message}`);
+      return {
+        valid: false,
+        deployable: false,
+        errors: [error.message],
+        findings: [],
+        deployFindings: [],
+        notRun: [],
+        signalPath: null
+      };
+    }
+  }
+
   /**
    * Finalize validation results and generate proof if successful
    */
@@ -740,7 +885,10 @@ class ValidationOrchestrator {
 
       this.logger.info(`[ValidationOrchestrator] Proof saved: ${this.proofPath}`);
     } catch (error) {
-      throw new Error(`Failed to save proof: ${error.message}`);
+      throw new Error(`[ValidationOrchestrator] Failed to save the validation proof to ${this.proofPath} `
+        + `- Expected the conn-runtime directory to be writable. Fix: repair whatever the cause names `
+        + `(${error.message})`,
+      { cause: error });
     }
   }
 }