@onlineapps/conn-orch-validator 10.0.0 → 12.0.0

package/manifests/biz-service.manifest.json

@@ -108,7 +108,7 @@
     ],
     "own": {
       "concern": "the files of the template whose CONTENT the service decides, and the reason each is not held to the platform's copy",
-      "why": "a file added to the template is a decision about who guards it, and this class is the decision written down: no row holds these to the template, because their content IS the service. Dockerfile is the exception that proves the rule - its one platform fact, the node major, is R-NODE's row, and everything else in it is this service's build. docs/README.md is the same decision for the map of the documentation tree: which branches a service has is the service's, and what the platform holds the tree to is not that prose but D-LINT, which asks the documentation lint whether the tree is clean. It is the map alone, not docs/ - the three installation documents under docs/80-setup/ ARE held to a skeleton, and a class covering them would exempt what a row requires. The class exists so that the completeness check of finding 18 has an answer other than silence for every file the template carries (automation-gates.md \u00a75)",
+      "why": "a file added to the template is a decision about who guards it, and this class is the decision written down: no row holds these to the template, because their content IS the service. Dockerfile is the exception that proves the rule - its TWO platform facts are rows of their own, and everything else in it is this service's build: the node major is R-NODE's row, and WHICH USER the process runs as is R-USER's (added d.588c, after a production image built from the template was measured running as uid 0 while the dev container beside it ran as 1000). What a service BUILDS is its own; what it RUNS AS is the platform's. docs/README.md is the same decision for the map of the documentation tree: which branches a service has is the service's, and what the platform holds the tree to is not that prose but D-LINT, which asks the documentation lint whether the tree is clean. It is the map alone, not docs/ - the three installation documents under docs/80-setup/ ARE held to a skeleton, and a class covering them would exempt what a row requires. The class exists so that the completeness check of finding 18 has an answer other than silence for every file the template carries (automation-gates.md \u00a75)",
       "allowed": [
         "Dockerfile",
         "index.js",
@@ -446,7 +446,7 @@
         "from": { "path": "api/config/shared-env.json", "text": true },
         "severity": "deploy",
         "owner": "BIZ-general",
-        "why": "the shared key set is one fact with one owner; measured on 2026-09-09, none of the nine copies matched the platform file and one key existed in no copy at all. The owner is api/config/shared-env.json and this row renders from it with the renderer the sync command writes with, so a service cannot be synced and reported drifted in the same hour; a run that cannot reach the workspace says NOT RUN and names the command, because a render published with this package answers about the day it was published, not about the SSOT",
+        "why": "the shared key set is one fact with one owner; measured on 2026-09-09, none of the nine copies matched the platform file and one key existed in no copy at all. The owner is api/config/shared-env.json and this row renders from it with the renderer the sync command writes with, so a service cannot be synced and reported drifted in the same hour; a run that cannot REACH the workspace says NOT RUN and names the command, because a render published with this package answers about the day it was published, not about the SSOT; a run that does reach it and finds no api/config/shared-env.json in the api checkout stops instead - a missing SSOT in a workspace the run can read is a finding and never a NOT RUN (automation-gates.md §5), and the message names the checkout to update and the api ref a CI job has to move",
         "fix": "npx oa-sync-template shared-env --target .",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a718"
       },
@@ -497,6 +497,20 @@
         "fix": "in docker-compose.yml set the service block's command to [\"node\", \"index.js\"] (the entrypoint init.sh execs it, so node becomes PID 1), then recreate the container and smoke it",
         "doc": "api/docs/governance/confirmations/biz-compose-pid1.md"
       },
+      {
+        "id": "R-USER",
+        "check": "process-identity",
+        "image_path": "Dockerfile",
+        "image_stage": "production",
+        "path": "docker-compose.yml",
+        "service_user": "node",
+        "service_uid": "1000:1000",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "WHICH USER the process is, which is a platform fact and not a service build. Measured 2026-09-17 on a production image built from the platform template: `docker run --rm <image> id` answered uid=0(root) gid=0(root), while the dev container beside it ran as 1000:1000 because docker-compose.yml pins it - nobody had decided that difference, the production stage simply declared no USER, and nothing in the uniform could say so because Dockerfile is a file of the own class. This row is the SECOND platform fact carved out of that class, for the same reason as the first (R-NODE, the node major): what a service BUILDS is its own, what it RUNS AS is the platform. It measures the two places nothing else holds - the production stage of the Dockerfile, which is the stage CI builds and the one the defect lived in, and the SERVICE node of the dev compose. The runner user: sits inside the block F-RUNNER holds byte for byte, and the production compose is the whole-file render of G-PROD, so neither is repeated here (change-discipline.md, One rail per concern). The two spellings are ONE identity, and the row carries both because no machine resolves an account name to a uid without the image: node is uid 1000, gid 1000 in the node images this platform builds on, measured docker run --rm node:24-alpine id node",
+        "fix": "in the production stage of Dockerfile put RUN mkdir -p /app/logs /app/conn-runtime && chown -R node:node /app, then USER node before npm ci, and --chown=node:node on both COPY lines; in docker-compose.yml give the service node the line user: \"1000:1000\"",
+        "doc": "api/docs/biz/00-model/service-shape.md"
+      },
       {
         "id": "R-PORTS-DEV",
         "check": "compose-no-ports",
@@ -587,6 +601,19 @@
         "fix": "set DB_USER in this service's env template to oagen_<shortname>, where <shortname> is what config/service/config.json declares; the account and its grants are created by the operator installing the schema",
         "doc": "api/docs/governance/confirmations/db-accounts-per-service.md"
       },
+      {
+        "id": "D-DB-CI-ACCOUNT",
+        "check": "db-ci-account",
+        "path": ".gitlab-ci.yml",
+        "block": "oa-ci v1",
+        "key": "DB_USER",
+        "account": "root",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "D-DB-ACCOUNT one row up measures the DECLARATION - the account production installs. Nothing measured the ONE environment where that migration set is applied every day. Measured 2026-09-16 over the eight biz repositories: seven set DB_USER: \"root\" in their test job while declaring oagen_<service> in the env template, so CI proved the set under rights no production box grants - the gap db-migrations-first-deploy 001 names (\"migrace nikdy pod rootem\") in the only place a migration can be tried before a deploy. A separate row and not a wider D-DB-ACCOUNT: another file, another fix, and one row with two fixes is two mechanisms under one name (automation-gates.md §1.2). It reads the lines OUTSIDE the oa-ci v1 block, because that block is the platform's and G-CI compares it byte for byte; reading a region and not the whole file is also what keeps it clear of the defect that had the whole-file row over .gitlab-ci.yml withdrawn after three days. It asks WHO the database steps run as and deliberately not WHETHER a repository runs them: a job that builds no schema has no account for the step to create, and demanding one would be this row inventing a rule (truth-over-agreement.md §6). Silent for a service with no database block by construction - pdfgen is the live case",
+        "fix": "in the test job of .gitlab-ci.yml set DB_USER to the account config/env-templates/<service>.env declares, give DB_PASSWORD a throwaway value of the job, name the sidecar's root credential CI_DB_ROOT_USER / CI_DB_ROOT_PASSWORD, and run `npx oa-biz-ci-gate setup-db-account` as the first before_script step, before ci:gate:setup",
+        "doc": "api/docs/governance/confirmations/db-accounts-per-service.md"
+      },
       {
         "id": "D-DB-HEADERS",
         "check": "install-contract",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "10.0.0",
+  "version": "12.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"
@@ -28,6 +28,7 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
+    "@onlineapps/cookbook-core": "6.0.0",
     "@onlineapps/logger-contract": "2.0.0",
     "@onlineapps/service-validator-core": "2.1.0"
   },

package/src/CookbookTestRunner.js

@@ -10,6 +10,8 @@ const {
   describeStepFailure, describeStepIdentity, KIND_STEP, KIND_COOKBOOK_LOAD_FAILURE
 } = require('./utils/stepFailure');
 const { parseHandlerRef, resolveHandlerModule } = require('./utils/handlerRef');
+const { createRunContext, resolveStepInput, recordStepOutcome, checkStepInputExpressions }
+  = require('./utils/stepReferences');
 const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
@@ -168,6 +170,17 @@ class CookbookTestRunner {
     // along, so the catching layer still sees the original error object.
     try {
       this.validateCookbook(cookbookData);
+
+      // What the recipe WRITES, before anything of it runs. A helper call and a
+      // `{{steps.<id>}}` naming no step of this cookbook are both refused here:
+      // production evaluates the first and refuses the second at submission, so
+      // letting either through as literal text would make a green Tier-1 say
+      // more than production will (utils/stepReferences.js). The step values
+      // themselves are resolved per step, later and against what ran.
+      const referenceProblem = await checkStepInputExpressions(readCookbookSteps(cookbookData.steps));
+      if (referenceProblem !== null) {
+        throw new Error(`[CookbookTestRunner] ${referenceProblem}`);
+      }
     } catch (error) {
       if (typeof cookbook === 'string') {
         throw new Error(`${error.message} (cookbook file: ${cookbook})`, { cause: error });
@@ -190,8 +203,19 @@ class CookbookTestRunner {
     // Execute steps
     const cookbookName = cookbookData.description || 'Unnamed';
     const stepResults = [];
+    // What the steps of THIS cookbook have produced so far — the scope a
+    // `{{steps.<step_id>.output.…}}` reference resolves against
+    // (src/utils/stepReferences.js). It is built here, per cookbook, because
+    // `runCookbooks()` drives many cookbooks through one runner and a step of
+    // one must never see a step of another.
+    const runContext = createRunContext();
     for (const [stepIndex, step] of stepsArray.entries()) {
-      const stepResult = await this.executeStep(step, testConfig, stepIndex, cookbookData.defaults);
+      const stepResult = await this.executeStep(step, testConfig, stepIndex, cookbookData.defaults, runContext);
+      // Every step is recorded — passed or failed. `recordStepOutcome` decides
+      // what an entry carries; a failed step keeps its status and no output, so
+      // a reference into it stays literal (the section "Runtime context
+      // (`context.steps`)" of api/docs/biz/40-cookbooks/format.md).
+      recordStepOutcome(runContext, step, stepResult);
       // Which cookbook this step came from. Without it a failed step in the
       // aggregate is an id with no file behind it, and a service can carry a
       // dozen cookbooks (utils/stepFailure.js).
@@ -385,9 +409,21 @@ class CookbookTestRunner {
   }
 
   /**
-   * Execute single step
+   * Execute single step.
+   *
+   * @param {Object} step - the cookbook step as written
+   * @param {Object} testConfig - the cookbook's `test` block
+   * @param {number} [stepIndex] - the step's position, for messages
+   * @param {Object|null} [cookbookDefaults] - the cookbook's `defaults` block
+   * @param {{steps: Object}} [runContext] - what earlier steps of this cookbook
+   *        produced (`utils/stepReferences`). A step executed on its own has no
+   *        earlier steps, so the default is an EMPTY context — the accurate
+   *        value for that case, not a stand-in for a missing one: every
+   *        `{{steps.…}}` reference then resolves to nothing and survives as
+   *        literal text, exactly as the format prescribes.
+   * @returns {Promise<Object>} the step result record
    */
-  async executeStep(step, testConfig, stepIndex = 0, cookbookDefaults = null) {
+  async executeStep(step, testConfig, stepIndex = 0, cookbookDefaults = null, runContext = createRunContext()) {
     const startTime = Date.now();
 
     // ONE label for this step, resolved once. `step.id` alone was undefined for
@@ -460,8 +496,16 @@ class CookbookTestRunner {
       // { modulePath, exportName } (v3 handler dispatch is the only mode).
       const spec = await this.resolveOperation(step.service, step.operation);
 
+      // WHAT THE HANDLER IS ACTUALLY CALLED WITH. The step's `input` is the
+      // cookbook's text; a `{{steps.<step_id>.output.…}}` reference in it is
+      // resolved HERE, against what the earlier steps of this cookbook returned.
+      // Inside the try, so an evaluator error becomes this step's failure and
+      // not the whole run's.
+      const input = await resolveStepInput(step, runContext);
+
       await this._dispatchViaHandler({
         step,
+        input,
         spec,
         testConfig,
         validationTenantId,
@@ -562,7 +606,7 @@ class CookbookTestRunner {
    * all connector slots set to null — handlers that need DB access use
    * direct sequelize import per biz/60-templates/onboarding-checklist.md §9a.
    */
-  async _dispatchViaHandler({ step, spec, testConfig, validationTenantId, validationWorkspaceId, result, startTime }) {
+  async _dispatchViaHandler({ step, input, spec, testConfig, validationTenantId, validationWorkspaceId, result, startTime }) {
     const stepTimeout = testConfig.timeout || this.timeout;
     const correlationId = step.correlation_id || crypto.randomUUID();
     // Production ctx (from ContextBuilder) always carries workflow_id + person_id.
@@ -619,7 +663,7 @@ class CookbookTestRunner {
       operation: step.operation,
       module: spec.modulePath,
       export: spec.exportName,
-      input: step.input,
+      input,
       ctx: {
         tenant_id: ctx.tenant_id,
         workspace_id: ctx.workspace_id,
@@ -656,7 +700,7 @@ class CookbookTestRunner {
     let handlerOutput = null;
     try {
       handlerOutput = await Promise.race([
-        Promise.resolve().then(() => handlerFn(step.input || {}, ctx)),
+        Promise.resolve().then(() => handlerFn(input || {}, ctx)),
         timeoutPromise
       ]);
     } catch (error) {

package/src/ValidationOrchestrator.js

@@ -25,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
@@ -76,6 +77,59 @@ function readStepMeasurement(step, field, 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
  *
@@ -383,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
       //
@@ -407,42 +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();
-      // Measured values only — see readStepMeasurement() for why `|| 0` here
-      // was the reason the generator's refusal never fired.
-      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) {
+      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.
         //
@@ -453,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
       //
@@ -467,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);
@@ -483,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
    */
@@ -500,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}`)]
       };
     }
   }
@@ -539,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: []
       };
     }
@@ -622,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: []
       };
     }
@@ -683,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}`)]
       };
     }
   }
@@ -730,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) {
@@ -766,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 });
@@ -788,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
@@ -844,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: [],