@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/ValidationOrchestrator.js

@@ -4,21 +4,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');
+// `ValidationProofVerifier` was destructured here alongside the codec and never
+// 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');
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
 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.
  *
@@ -28,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 = {}) {
@@ -46,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
@@ -77,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({
@@ -115,26 +126,83 @@ class ValidationOrchestrator {
 
 
 
+  /**
+   * Read and parse the service's package.json.
+   *
+   * It is the single source of truth for the service version — the same one
+   * validateConfig() names below, and the same one the biz pre-validation entry
+   * point (`src/utils/preValidation.js`) already reads. `config/service/config.json`
+   * cannot supply it: the wrapper's ConfigLoader
+   * (`api/shared/connector/service-wrapper/src/ConfigLoader.js`) assigns
+   * `config.service.version` from package.json unconditionally on every load, so
+   * the key in the file is dead — and where it is declared at all, biz services
+   * declare it as the unresolved literal `${npm_package_version}`.
+   *
+   * A missing, unreadable, unparseable or version-less package.json is a contract
+   * violation, not a computation hiccup, so it is raised here in full §5 shape
+   * rather than through calculateFingerprint()'s generic wrapper.
+   *
+   * @param {string} packageFile absolute path to the service's package.json
+   * @returns {object} the parsed package.json, `version` guaranteed non-empty
+   */
+  readServicePackageJson(packageFile) {
+    let raw;
+    try {
+      raw = fs.readFileSync(packageFile, 'utf8');
+    } catch (error) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json is unreadable - Expected: a readable ${packageFile}, `
+        + 'the single source of truth for the service version. '
+        + `Read failed with: ${error.code || error.message}. `
+        + 'Fix: point options.serviceRoot at the service directory that contains package.json.'
+      );
+    }
+
+    let pkg;
+    try {
+      pkg = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json is not valid JSON - Expected: parseable JSON at ${packageFile}. `
+        + `Parse failed with: ${error.message}. `
+        + 'Fix: repair the file.'
+      );
+    }
+
+    if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+      throw new Error(
+        `[ValidationOrchestrator] Service package.json has no version - Expected: a non-empty "version" string in ${packageFile}, `
+        + 'the single source of truth for the service version. '
+        + `Got: ${JSON.stringify(pkg.version)}. `
+        + 'Fix: set "version" in the service package.json.'
+      );
+    }
+
+    return pkg;
+  }
+
   /**
    * Calculate service fingerprint
    * Based on: version + operations.json + dependencies + config
    */
   async calculateFingerprint() {
+    const packageFile = path.join(this.serviceRoot, 'package.json');
+    const pkg = this.readServicePackageJson(packageFile);
+
     try {
       const configFile = path.join(this.configPath, 'config.json');
       const operationsFile = path.join(this.configPath, 'operations.json');
-      const packageFile = path.join(this.serviceRoot, 'package.json');
       const dockerFile = path.join(this.serviceRoot, 'Dockerfile');
       const dockerComposeFile = path.join(this.serviceRoot, 'docker-compose.yml');
       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'));
       const operations = JSON.parse(fs.readFileSync(operationsFile, 'utf8'));
-      const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
 
       // Include infra file contents in fingerprint to detect changes in environment/setup
       const infra = {};
@@ -187,8 +255,21 @@ class ValidationOrchestrator {
       }
 
       // Generate fingerprint using FingerprintUtils (handles deep sorting)
+      //
+      // The version comes from package.json alone. It used to read
+      // `config.service?.version || pkg.version`, which hashed a value that was
+      // not a version at all: `config.service.version` is overwritten by the
+      // wrapper's ConfigLoader on every load (see readServicePackageJson above),
+      // and the services that declare it leave the unresolved literal
+      // `${npm_package_version}` in that key. The `||` then hid it — for those
+      // services the package.json branch was never reached, so publishing a new
+      // version of one did not move its fingerprint by one bit
+      // (package.json is otherwise represented here only by its @onlineapps
+      // dependency pins). config.json's own content is still hashed below, so
+      // editing that key is still detected — as a config change, which is what
+      // it is.
       const fingerprintData = {
-        serviceVersion: config.service?.version || pkg.version,
+        serviceVersion: pkg.version,
         operations: operations,
         dependencies: deps,
         config: config,
@@ -197,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:
@@ -246,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;
@@ -261,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;
@@ -275,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;
@@ -286,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) {
@@ -295,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;
@@ -306,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
@@ -322,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);
 
@@ -351,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)
-      }
-
-      // 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');
-        }
-      }
+      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));
 
-      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.
@@ -407,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 || {})) {
@@ -417,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>'`);
         }
 
@@ -474,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
@@ -498,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) {
@@ -506,6 +646,7 @@ class ValidationOrchestrator {
         total: 0,
         passed: 0,
         failed: 0,
+        cookbooks: { total: 0, passed: 0, failed: 0 },
         errors: [`Cookbook tests failed: ${error.message}`]
       };
     }
@@ -594,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
    */
@@ -665,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 });
     }
   }
 }