@onlineapps/conn-orch-validator 12.1.1 → 13.0.0

package/src/CookbookTestUtils.js

@@ -1,8 +1,11 @@
 'use strict';
 
+const {
+  validateCookbook: validateCookbookFormat,
+  CookbookValidationError
+} = require('@onlineapps/cookbook-core');
 const {
   MIN_COOKBOOK_FORMAT_VERSION,
-  checkCookbookFormatVersion,
   readCookbookSteps,
   stepIdentityOf
 } = require('./utils/cookbookFormat');
@@ -10,6 +13,9 @@ const {
 /**
  * CookbookTestUtils - Utilities for cookbook testing
  */
+/** The control-flow step types the V2.1 schema knows. */
+const CONTROL_FLOW_TYPES = ['foreach', 'switch', 'fork_join', 'steps'];
+
 class CookbookTestUtils {
   /**
    * Create a mock workflow message
@@ -65,59 +71,38 @@ class CookbookTestUtils {
   }
 
   /**
-   * Validate cookbook structure (basic validation)
+   * Validate a cookbook for the readiness-wrapper path
+   * (`ServiceReadinessValidator.checkCookbookExecution`).
+   *
+   * FIRST, `@onlineapps/cookbook-core` `validateCookbook` — the same function
+   * the Tier-1 runner (`CookbookTestRunner.validateCookbook`, d.980) and the
+   * receiving side run. It owns every structural rule this entry point used to
+   * copy: the object itself, `version`, the `steps` array, a step's `step_id`,
+   * `type` and `service`, and a step carrying `id` (d.983). Until d.984 this
+   * method held its own copy of each, with its own messages, and the `id` ban
+   * stayed behind cookbook-core until d.985 — one concern on two rails
+   * (`.claude/rules/change-discipline.md` § One rail per concern).
+   *
+   * This entry point answers with a list, not an exception, so a refusal
+   * becomes the list's one error. From cookbook-core only a
+   * `CookbookValidationError` is a finding about the cookbook; anything else it
+   * throws is a defect and propagates (the caller,
+   * `checkCookbookExecution`, reports it as a failed check).
    *
-   * The format-version rule is the shared one (`utils/cookbookFormat`), the
-   * same rule the Tier-1 `CookbookTestRunner` enforces — one fact, one owner.
-   * Presence alone used to be enough here, so a cookbook stuck on an outdated
-   * format passed the readiness wrapper unnoticed.
+   * @param {*} cookbook - the parsed cookbook
+   * @returns {{valid: boolean, errors: string[]}}
    */
   static validateCookbook(cookbook) {
-    const errors = [];
-
-    if (!cookbook) {
-      errors.push('Cookbook is required');
-      return { valid: false, errors };
-    }
-
-    const versionProblem = checkCookbookFormatVersion(cookbook.version);
-    if (versionProblem) {
-      errors.push(versionProblem);
-    }
-
-    // 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 = readCookbookSteps(cookbook.steps);
+      validateCookbookFormat(cookbook);
     } 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.
-      errors.push(error.message);
-      return { valid: false, errors };
-    }
-
-    if (steps.length === 0) {
-      errors.push('Steps array is required');
-    } else {
-      steps.forEach((step, index) => {
-        if (!stepIdentityOf(step)) {
-          errors.push(`Step ${index}: step_id is required`);
-        }
-        if (!step.type) {
-          errors.push(`Step ${index}: type is required`);
-        }
-        if (step.type === 'task' && !step.service) {
-          errors.push(`Step ${index}: service is required for task steps`);
-        }
-      });
+      if (!(error instanceof CookbookValidationError)) {
+        throw error;
+      }
+      return { valid: false, errors: [error.message] };
     }
 
-    return {
-      valid: errors.length === 0,
-      errors
-    };
+    return { valid: true, errors: [] };
   }
 
   /**
@@ -212,50 +197,76 @@ class CookbookTestUtils {
   }
 
   /**
-   * Generate control flow step (foreach, switch, etc.)
+   * Generate a control-flow step (`foreach`, `switch`, `fork_join`, `steps`) in
+   * the shape the V2.1 schema of `@onlineapps/cookbook-core` accepts.
+   *
+   * The step names the service that runs it, and every task it nests by default
+   * runs in that same service
+   * (api/docs/governance/confirmations/cookbook-execution-owner.md 002,
+   * api/docs/biz/40-cookbooks/format.md). Nested steps passed in `options`
+   * (`body`, `cases`, `default`, `branches`, `steps`) are taken as given.
+   *
+   * @param {'foreach'|'switch'|'fork_join'|'steps'} type
+   * @param {object} options
+   * @param {string} options.service - the service that runs the step (required)
+   * @param {string} [options.step_id] - defaults to `<type>_step_<timestamp>`
+   * @returns {object} one control-flow step
+   * @throws {Error} on a missing `service`, a V1 `id` option or an unknown type
    */
   static createControlFlowStep(type, options = {}) {
+    if (!CONTROL_FLOW_TYPES.includes(type)) {
+      throw new Error(`[CookbookTestUtils] createControlFlowStep('${type}') - unknown control-flow type '${type}' - Expected: one of ${CONTROL_FLOW_TYPES.join(', ')}. Fix: pass one of them as the first argument`);
+    }
+    if (typeof options.service !== 'string' || options.service.length === 0) {
+      throw new Error(`[CookbookTestUtils] createControlFlowStep('${type}') - \`service\` is required - Expected: the name of the service that runs this control-flow step. Fix: pass { service: '<name>' }`);
+    }
+    if (Object.prototype.hasOwnProperty.call(options, 'id')) {
+      throw new Error(`[CookbookTestUtils] createControlFlowStep('${type}') - \`id\` is not a step identity - Expected: \`step_id\` (the schema refuses \`id\` on every step). Fix: pass { step_id: '<id>' }`);
+    }
+
+    const { service } = options;
+    const task = (stepId, operation) => ({ step_id: stepId, type: 'task', service, operation });
     const baseStep = {
-      step_id: options.step_id || options.id || `${type}-step-${Date.now()}`,
-      type
+      step_id: options.step_id || `${type}_step_${Date.now()}`,
+      type,
+      service
     };
 
     switch (type) {
       case 'foreach':
         return {
           ...baseStep,
-          items: options.items || '$api_input.items',
-          body: options.body || {
-            step_id: 'foreach-body',
-            type: 'task',
-            service: 'test-service',
-            operation: 'processItem'
-          }
+          iterator: options.iterator || '{{api_input.items}}',
+          body: options.body || [task('foreach_body', 'processItem')]
         };
 
       case 'switch':
         return {
           ...baseStep,
-          condition: options.condition || '$api_input.type',
-          cases: options.cases || [
-            { value: 'type1', step: { step_id: 'case1', type: 'task', service: 'service1' } },
-            { value: 'type2', step: { step_id: 'case2', type: 'task', service: 'service2' } }
-          ],
-          default: options.default || { step_id: 'default', type: 'task', service: 'default-service' }
+          expression: options.expression || '{{api_input.type}}',
+          cases: options.cases || {
+            type1: task('case1', 'handleType1'),
+            type2: task('case2', 'handleType2')
+          },
+          default: options.default || task('default_case', 'handleDefault')
         };
 
       case 'fork_join':
         return {
           ...baseStep,
-          branches: options.branches || [
-            { step_id: 'branch1', type: 'task', service: 'service1' },
-            { step_id: 'branch2', type: 'task', service: 'service2' }
-          ],
+          branches: options.branches || {
+            branch1: task('branch1', 'runBranch1'),
+            branch2: task('branch2', 'runBranch2')
+          },
           join: options.join || { strategy: 'merge' }
         };
 
+      case 'steps':
       default:
-        return baseStep;
+        return {
+          ...baseStep,
+          steps: options.steps || [task('steps_first', 'runFirst')]
+        };
     }
   }
 }

package/src/ServiceReadinessValidator.js

@@ -2,7 +2,15 @@
 
 const { assertLogger } = require('@onlineapps/logger-contract');
 const CookbookTestUtils = require('./CookbookTestUtils');
-const { HANDLER_REF_PATTERN } = require('./utils/handlerRef');
+const { operationsRuleSentences } = require('./utils/operationsRules');
+const {
+  operationsMapFindings,
+  operationsDeclarationFindings,
+  documentFindingSentence,
+  ofSeverity,
+  SEVERITY_ERROR,
+  SEVERITY_WARNING
+} = require('./utils/operationsDocumentRules');
 
 /**
  * The semver 2.0.0 grammar, verbatim from semver.org's own published regular
@@ -41,8 +49,8 @@ const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]
  * 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)
- * @see /api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md
+ * @see api/docs/biz/40-cookbooks/test-runner-flow.md (input probe contract)
+ * @see api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md
  */
 class ServiceReadinessValidator {
   constructor(options = {}) {
@@ -51,7 +59,7 @@ class ServiceReadinessValidator {
     // it. Until then this class demanded a logger and never wrote a line, so a
     // 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.
+    // api/docs/governance/confirmations/connector-logger-contract.md 001.
     this.logger = assertLogger(
       'ServiceReadinessValidator',
       options.logger,
@@ -60,7 +68,7 @@ class ServiceReadinessValidator {
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
     // Core checks ALWAYS run, optional checks run if testCookbook/registry provided
-    // See: /shared/connector/conn-orch-validator/README.md for usage pattern
+    // See: api/shared/connector/conn-orch-validator/README.md for usage pattern
     //
     // Weight allocation post-ADR-0005:
     //   operations: 80 — was 60; absorbed the 20 pts from retired `health`.
@@ -205,59 +213,41 @@ class ServiceReadinessValidator {
 
   /**
    * Check operations.json compliance (v3 — handler registry).
-   * Required per operation: description, handler, bundle_scope, input, output.
-   * Forbidden (v2): endpoint, method, path.
+   *
+   * The per-operation rules are the Registry's own, read from the one
+   * definition that owns them (`utils/operationsRules.js` →
+   * `@onlineapps/service-validator-core`); `input` and `output` are this
+   * check's own requirement, because the readiness run synthesises a cookbook
+   * from them, and a missing `description` is a warning.
+   *
+   * @see api/docs/governance/confirmations/operations-schema-mirror.md
    */
   async checkOperationsCompliance(operations) {
     try {
       const errors = [];
       const warnings = [];
 
-      if (!operations || typeof operations !== 'object') {
-        return {
-          passed: false,
-          error: 'Operations must be an object'
-        };
-      }
-
-      const operationCount = Object.keys(operations).length;
-      if (operationCount === 0) {
-        return {
-          passed: false,
-          error: 'No operations defined'
-        };
-      }
-
-      const validScopes = ['platform', 'tenant', 'workspace'];
-      const forbiddenV2Fields = ['endpoint', 'method', 'path'];
-
-      for (const [name, operation] of Object.entries(operations)) {
-        if (!operation.description) {
-          warnings.push(`Operation '${name}' missing description`);
-        }
-        if (!operation.handler) {
-          errors.push(`Operation '${name}' missing handler (v3 — 'handlers/<path>#<export>')`);
-        } else if (!HANDLER_REF_PATTERN.test(operation.handler)) {
-          errors.push(`Operation '${name}' has invalid handler ref: '${operation.handler}'`);
-        }
-        if (!operation.bundle_scope) {
-          errors.push(`Operation '${name}' missing bundle_scope (platform|tenant|workspace)`);
-        } else if (!validScopes.includes(operation.bundle_scope)) {
-          errors.push(`Operation '${name}' has invalid bundle_scope: '${operation.bundle_scope}'`);
-        }
-        if (!operation.input) {
-          errors.push(`Operation '${name}' missing input schema`);
-        }
-        if (!operation.output) {
-          errors.push(`Operation '${name}' missing output schema`);
-        }
-
-        for (const forbidden of forbiddenV2Fields) {
-          if (forbidden in operation) {
-            errors.push(`Operation '${name}' has retired v2 field '${forbidden}' — remove per RFC §5.3`);
-          }
-        }
-      }
+      // A map with nothing in it — asked of the one definition that owns that
+      // rule. This rail was the strict one of four before d.465b; it still
+      // refuses, but now it refuses in the same sentence as every other rail
+      // instead of one it wrote itself.
+      errors.push(...operationsMapFindings(operations).map(documentFindingSentence));
+
+      // The Registry's rules, asked of the one definition that owns them —
+      // including "the map must be a plain object", which this method used to
+      // answer on its own.
+      errors.push(...operationsRuleSentences(operations).sentences);
+
+      const isMap = operations !== null && typeof operations === 'object' && !Array.isArray(operations);
+      const operationCount = isMap ? Object.keys(operations).length : 0;
+
+      // A declaration complete enough for the cookbook this validator
+      // synthesises from it — the same question step 4 of the boot validation
+      // asks, asked of the same definition since d.465c, so the two can no
+      // longer answer it in two different sentences.
+      const declaration = operationsDeclarationFindings(operations);
+      errors.push(...ofSeverity(declaration, SEVERITY_ERROR).map(documentFindingSentence));
+      warnings.push(...ofSeverity(declaration, SEVERITY_WARNING).map(documentFindingSentence));
 
       return {
         passed: errors.length === 0,

package/src/ValidationOrchestrator.js

@@ -17,9 +17,24 @@ const ValidationProofGenerator = require('./validators/ValidationProofGenerator'
 const { VALIDATOR_VERSION } = require('./validatorIdentity');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
+// Where the proof file lives is ONE fact of this package, and its owner is the
+// module that writes it in the CI gate. Until d.758 this class built the same
+// path from a literal of its own, so the boot path and the gate path each
+// carried a copy — and two copies of one fact agree only while somebody is
+// watching (`.claude/rules/doc-code-binding.md` §1). The wrapper's pair ended
+// the same way in d.715 (`ConfigLoader.PROOF_RELATIVE_PATH`).
+const { PROOF_RELATIVE_PATH } = require('./utils/preValidation');
 const CookbookTestRunner = require('./CookbookTestRunner');
 const { assertLogger } = require('@onlineapps/logger-contract');
-const { HANDLER_REF_PATTERN } = require('./utils/handlerRef');
+const { operationsRuleSentences } = require('./utils/operationsRules');
+const {
+  operationsDocumentFindings,
+  operationsDeclarationFindings,
+  documentFindingSentence,
+  ofSeverity,
+  SEVERITY_ERROR,
+  SEVERITY_WARNING
+} = require('./utils/operationsDocumentRules');
 const { loadManifest, DEFAULT_MANIFEST_PATH } = require('./manifest/loadManifest');
 const { runManifest } = require('./manifest/runManifest');
 const { resolveWorkspaceRoot } = require('./manifest/workspaceRoot');
@@ -172,7 +187,7 @@ class ValidationOrchestrator {
     // hands the same object to CookbookTestRunner below, which demands all four.
     // 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.
+    // api/docs/governance/confirmations/connector-logger-contract.md 001.
     this.logger = assertLogger(
       'ValidationOrchestrator',
       options.logger,
@@ -186,8 +201,8 @@ class ValidationOrchestrator {
     // failure one layer away from the cause.
     this.configPath = path.join(this.serviceRoot, 'config', 'service');
 
-    this.runtimePath = path.join(this.serviceRoot, 'conn-runtime');
-    this.proofPath = path.join(this.runtimePath, 'validation-proof.json');
+    this.proofPath = path.join(this.serviceRoot, PROOF_RELATIVE_PATH);
+    this.runtimePath = path.dirname(this.proofPath);
 
     // The manifest run of THIS validation, computed on first use (manifestRun()).
     // One orchestrator is one run: `ServiceWrapper._createValidationOrchestrator()`
@@ -455,6 +470,15 @@ class ValidationOrchestrator {
       const structureFailed = await this.runStep(results, 'structure', async () => {
         this.logger.info('[ValidationOrchestrator] Step 1/7: Service Structure');
         results.steps.structure = await this.validateStructure();
+        // Step 1 collects its warnings like step 4 does. Until d.791c it was the
+        // only step that did not: twelve `this.warnings.push(…)` in
+        // `ServiceStructureValidator` filled a field the summary never read, so
+        // findings like STANDARD_LEVEL_GAP reached no operator. Measured over all
+        // eight `api_biz/*` before the change: exactly ONE warning appears
+        // (ingest), so the symmetry arrived with compliance rather than with a
+        // flood (`automation-gates.md` §3). Before the push, because a failing
+        // structure returns below and its warnings are worth just as much.
+        results.warnings.push(...attributeToStep(results.steps.structure.warnings || [], 'structure'));
         if (results.steps.structure.valid) return false;
 
         results.success = false;
@@ -721,11 +745,20 @@ class ValidationOrchestrator {
 
   /**
    * Step 4: Validate operations compliance (v3 — handler registry dispatch).
-   * Required per operation: handler ('handlers/<path>#<export>'), bundle_scope, input, output.
-   * Forbidden (v2): endpoint, method, path.
-   * Warned about: a missing `description` — inherited from the removed
-   * readiness step, which was the only place that noticed it and then threw
-   * the notice away.
+   *
+   * The per-operation rules are the Registry's, asked of the one definition
+   * that owns them (`utils/operationsRules.js` →
+   * `@onlineapps/service-validator-core`), so this step refuses exactly what a
+   * registration would refuse — including `mutates`, `resource_type` and the
+   * kebab-case key rule, which the copy that used to live here did not know.
+   *
+   * Two things this step checks beyond them, because a boot needs them and a
+   * registration does not: `input` and `output` must be declared (error), and a
+   * missing `description` is warned about — inherited from the removed
+   * readiness step, which was the only place that noticed it and then threw the
+   * notice away.
+   *
+   * @see api/docs/governance/confirmations/operations-schema-mirror.md
    */
   async validateOperations() {
     try {
@@ -734,39 +767,27 @@ class ValidationOrchestrator {
       const errors = [];
       const warnings = [];
 
-      const validScopes = ['platform', 'tenant', 'workspace'];
-      const forbiddenV2Fields = ['endpoint', 'method', 'path'];
-
-      for (const [opName, opDef] of Object.entries(operations.operations || {})) {
-        if (!opDef.description) {
-          warnings.push(`Operation ${opName}: missing description`);
-        }
-
-        if (!opDef.handler) {
-          errors.push(`Operation ${opName}: missing handler (v3 — 'handlers/<path>#<export>')`);
-        } else if (!HANDLER_REF_PATTERN.test(opDef.handler)) {
-          errors.push(`Operation ${opName}: invalid handler ref '${opDef.handler}' — expected 'handlers/<path>#<exportName>'`);
-        }
-
-        if (!opDef.bundle_scope) {
-          errors.push(`Operation ${opName}: missing bundle_scope (platform|tenant|workspace)`);
-        } else if (!validScopes.includes(opDef.bundle_scope)) {
-          errors.push(`Operation ${opName}: invalid bundle_scope '${opDef.bundle_scope}' — expected one of ${validScopes.join(', ')}`);
-        }
-
-        if (!opDef.input) {
-          errors.push(`Operation ${opName}: missing input schema`);
-        }
-        if (!opDef.output) {
-          errors.push(`Operation ${opName}: missing output schema`);
-        }
-
-        for (const forbidden of forbiddenV2Fields) {
-          if (forbidden in opDef) {
-            errors.push(`Operation ${opName}: retired v2 field '${forbidden}' present — remove per RFC §5.3`);
-          }
-        }
-      }
+      // The two DOCUMENT rules (`schema_version`, an operations map with
+      // nothing in it), asked of the one definition that owns them. Until
+      // d.465b this step was the rail that answered an empty map with silence
+      // — a clean PASS — while three other rails called the same document
+      // broken.
+      errors.push(...operationsDocumentFindings(operations).map(documentFindingSentence));
+
+      // Every rule the Registry refuses a registration on, asked once, of the
+      // one definition that owns them (`utils/operationsRules.js`). A missing
+      // `operations` key is one of them — it used to be read as `|| {}` here,
+      // which turned the Registry's refusal into a silent PASS.
+      const map = operations.operations;
+      errors.push(...operationsRuleSentences(map).sentences);
+
+      // What the Registry does NOT check, and this step does: a declaration
+      // complete enough for a cookbook to be generated from it. The readiness
+      // score asks the same question, and until d.465c the two worded every
+      // answer differently, which is two rails however identical the severity.
+      const declaration = operationsDeclarationFindings(map);
+      errors.push(...ofSeverity(declaration, SEVERITY_ERROR).map(documentFindingSentence));
+      warnings.push(...ofSeverity(declaration, SEVERITY_WARNING).map(documentFindingSentence));
 
       this.logger.info(`[ValidationOrchestrator] ✓ Operations compliance: ${errors.length === 0 ? 'PASS' : 'FAIL'}`
         + `${warnings.length > 0 ? ` (${warnings.length} warning(s))` : ''}`);
@@ -953,7 +974,7 @@ class ValidationOrchestrator {
    *
    * 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
+   * checkout and carries neither a compose file nor a README, 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
@@ -983,7 +1004,7 @@ class ValidationOrchestrator {
       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
+        // reverse — a reader acting on a missing-README finding 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 '

package/src/cli/biz-ci-gate.js

@@ -418,7 +418,7 @@ function runSetupDbAccount(options) {
 
 /**
  * Build the schema the contract declares. One implementation for every service:
- * the repo declares WHAT, this decides HOW (docs/biz/00-model/uniformity-principle.md).
+ * the repo declares WHAT, this decides HOW (api/docs/biz/00-model/uniformity-principle.md).
  */
 function runSetupDb(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
@@ -608,7 +608,7 @@ function exitWhenFlushed(code) {
  * and pass `service.url` to the runner, which never read it (`this.serviceUrl`
  * appears nowhere in CookbookTestRunner). `ConfigLoader.loadAll` no longer
  * returns that field either — the owner removed `port` and `url` from the
- * service shape (docs/governance/confirmations/biz-service-port-url.md 001), so
+ * service shape (api/docs/governance/confirmations/biz-service-port-url.md 001), so
  * the value had been `undefined` for every service on the platform. What the
  * load still did was make a readable config, an installed wrapper and a
  * resolvable `${ENV}` placeholder preconditions of a cookbook run that depends