@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/CookbookTestRunner.js

@@ -6,13 +6,11 @@ const crypto = require('crypto');
 const MockMQClient = require('./mocks/MockMQClient');
 const MockRegistry = require('./mocks/MockRegistry');
 const { resolveHeaders } = require('./utils/resolveHeaders');
-const { checkCookbookFormatVersion, normalizeCookbookSteps } = require('./utils/cookbookFormat');
-const { getTestNamespace } = require('./utils/testNamespace');
+const { checkCookbookFormatVersion, readCookbookSteps } = require('./utils/cookbookFormat');
+const { getTestNamespace, assertWorkspaceId } = require('./utils/testNamespace');
 const { describeStepFailure, describeStepIdentity } = require('./utils/stepFailure');
-
-// The logger methods this runner requires — the order is the order the error
-// message lists them in.
-const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+const { parseHandlerRef, resolveHandlerModule } = require('./utils/handlerRef');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
  * The step's stopwatch, spelled out. A single total hid the fact that
@@ -28,6 +26,55 @@ function describeStepTiming(result) {
     + ` = ${result.duration}ms total`;
 }
 
+/**
+ * Resolve one `expect.output` field name against a step's output.
+ *
+ * The name is a DOT PATH into nested objects, because that is the only way a
+ * cookbook can assert anything about a file descriptor: a descriptor lives
+ * under its own key inside the output (`{ pdf: <descriptor> }`), never at the
+ * root — api/docs/biz/40-cookbooks/variable-references.md § "File descriptors
+ * in outputs". A flat `actual[field]` lookup answered `undefined` for
+ * `"pdf.size"` and reported it as missing, which fails the step and, in
+ * Tier-1, the boot of a service returning exactly what the norm prescribes.
+ *
+ * Two rules, both decisions rather than consequences:
+ *
+ *   1. **The exact key wins, at every level.** `{ "a.b": 1 }` is legal output
+ *      and `"a.b"` is the name its author typed, so it is looked up verbatim
+ *      before the name is split. Splitting is what happens when the name does
+ *      not exist as written — nobody has to escape anything.
+ *   2. **Objects only.** A segment never indexes an array (`items.0` does not
+ *      reach the first element) and never reads a property off a scalar. No
+ *      cookbook asks for indices today; inventing the syntax here would make
+ *      it this library's invention rather than the norm's.
+ *
+ * @param {*} container - the output object, or any nested value during the walk
+ * @param {string} fieldPath - the field name as the cookbook wrote it
+ * @returns {{found: boolean, value?: *, missingSegment?: string}} `missingSegment`
+ *          is the FIRST segment that could not be resolved, so the caller can
+ *          say whether `pdf` was absent or `pdf` was there without a `size`.
+ */
+function resolveOutputField(container, fieldPath) {
+  const traversable = container !== null && typeof container === 'object' && !Array.isArray(container);
+
+  if (traversable && Object.prototype.hasOwnProperty.call(container, fieldPath)) {
+    return { found: true, value: container[fieldPath] };
+  }
+
+  const separator = fieldPath.indexOf('.');
+  if (separator === -1) {
+    return { found: false, missingSegment: fieldPath };
+  }
+
+  const head = fieldPath.slice(0, separator);
+  const rest = fieldPath.slice(separator + 1);
+  if (!traversable || !Object.prototype.hasOwnProperty.call(container, head)) {
+    return { found: false, missingSegment: head };
+  }
+
+  return resolveOutputField(container[head], rest);
+}
+
 /**
  * CookbookTestRunner — executes cookbook tests offline with mocked infrastructure.
  *
@@ -60,24 +107,8 @@ class CookbookTestRunner {
     // constructed fine and died on the first log line: delayed validation, which
     // architecture-principles.md §4 forbids. Owner confirmation:
     // docs/governance/confirmations/connector-logger-contract.md 001.
-    if (!options.logger) {
-      throw new Error(
-        '[CookbookTestRunner] Logger is required - Expected: a logger with info/warn/error/debug, '
-        + 'so the runner writes 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'
-    );
-    if (missingLoggerMethods.length > 0) {
-      throw new Error(
-        '[CookbookTestRunner] Logger is incomplete - Expected: info, warn, error, debug as functions; '
-        + `missing: ${missingLoggerMethods.join(', ')}. `
-        + 'Fix: pass a logger implementing all four.'
-      );
-    }
+    assertLogger('CookbookTestRunner', options.logger, 'the runner writes where the service writes');
+
     this.serviceName = options.serviceName;
     this.servicePath = options.servicePath;
     this.mockInfrastructure = options.mockInfrastructure !== false;
@@ -98,13 +129,7 @@ class CookbookTestRunner {
     }
 
     // Test results
-    this.results = {
-      total: 0,
-      passed: 0,
-      failed: 0,
-      duration: 0,
-      steps: []
-    };
+    this.results = this._emptyResults();
   }
 
   /**
@@ -125,6 +150,10 @@ class CookbookTestRunner {
     // path is appended to whatever the validation rejected — the reader of a
     // boot failure otherwise learns that "a" cookbook is malformed but not
     // which one, and a service can carry a dozen of them.
+    //
+    // The message opens with the cause's own message, so it INHERITS that
+    // error's `[Context]` rather than prefixing a second one; the cause travels
+    // along, so the catching layer still sees the original error object.
     try {
       this.validateCookbook(cookbookData);
     } catch (error) {
@@ -143,14 +172,14 @@ class CookbookTestRunner {
     this.logger.info(`Running cookbook: ${cookbookData.description || 'Unnamed'}`);
     this.logger.info(`Mode: ${testConfig.mode || 'production'}, Test: ${isTestMode}`);
 
-    // Convert steps to array format (support both V1 array and V2 object formats)
-    const stepsArray = this.normalizeSteps(cookbookData.steps);
+    // Already proved to be the array shape by validateCookbook above.
+    const stepsArray = readCookbookSteps(cookbookData.steps);
 
     // Execute steps
     const cookbookName = cookbookData.description || 'Unnamed';
     const stepResults = [];
     for (const [stepIndex, step] of stepsArray.entries()) {
-      const stepResult = await this.executeStep(step, testConfig, stepIndex);
+      const stepResult = await this.executeStep(step, testConfig, stepIndex, cookbookData.defaults);
       // 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).
@@ -185,16 +214,24 @@ class CookbookTestRunner {
     this.results.duration += results.duration;
     this.results.steps.push(...results.steps);
 
+    // One cookbook, counted as one — whatever its number of steps.
+    this.results.cookbooks.total += 1;
+    this.results.cookbooks[results.passed ? 'passed' : 'failed'] += 1;
+
     return results;
   }
 
   /**
-   * Run all cookbooks in a directory
+   * Run all cookbooks in a directory — or the ones running one operation.
    *
    * @param {string} cookbooksDir - Path to cookbooks directory
+   * @param {{operation?: string}} [options] - `operation` is a JavaScript
+   *        regular expression; only cookbooks containing a step whose
+   *        `operation` matches it are run. See `_selectCookbooks` for what
+   *        "selected" means and why the selection is per cookbook.
    * @returns {Object} Aggregate results
    */
-  async runCookbooks(cookbooksDir) {
+  async runCookbooks(cookbooksDir, options = {}) {
     // Every run reports ITS OWN run. `this.results` only ever accumulated, and
     // `ValidationOrchestrator` builds one runner in its constructor while
     // `ServiceWrapper._ensureValidationProof` reuses one orchestrator across
@@ -210,9 +247,13 @@ class CookbookTestRunner {
     // This is that caller.
     this.resetResults();
 
-    const files = fs.readdirSync(cookbooksDir).filter(f => f.endsWith('.json'));
+    const all = fs.readdirSync(cookbooksDir).filter(f => f.endsWith('.json'));
+    const files = this._selectCookbooks(cookbooksDir, all, options.operation);
 
-    this.logger.info(`Found ${files.length} cookbook(s) in ${cookbooksDir}`);
+    this.logger.info(options.operation === undefined
+      ? `Found ${files.length} cookbook(s) in ${cookbooksDir}`
+      : `Found ${files.length} of ${all.length} cookbook(s) in ${cookbooksDir}`
+        + ` matching operation /${options.operation}/`);
 
     for (const file of files) {
       const cookbookPath = path.join(cookbooksDir, file);
@@ -220,7 +261,22 @@ class CookbookTestRunner {
         await this.runCookbook(cookbookPath);
       } catch (error) {
         this.logger.error(`Failed to run cookbook ${file}:`, error.message);
+        // ONE definition for the step counters: everything in `results.steps` is
+        // counted in `total` exactly once — a real step, or the single entry
+        // below standing for a cookbook that never produced any. `failed++`
+        // without the matching `total++` is how the aggregate came to report
+        // `total 2 / failed 3` (BIZ-converter, 2026-08-26): numbers that do not
+        // add up, in the object `utils/preValidation.js` reads to decide whether
+        // to write a proof and `ValidationOrchestrator` folds into the run's
+        // totals. The invariant is `passed + failed === total === steps.length`.
+        this.results.total++;
         this.results.failed++;
+        // A cookbook that could not be loaded or validated is a FAILED cookbook,
+        // never a cookbook nobody counted: the file is there, it is part of the
+        // service's declared coverage, and a total that quietly excludes it
+        // reports a smaller run as a complete one.
+        this.results.cookbooks.total += 1;
+        this.results.cookbooks.failed += 1;
         this.results.steps.push({
           cookbook: file,
           passed: false,
@@ -232,10 +288,87 @@ class CookbookTestRunner {
     return this.results;
   }
 
+  /**
+   * Which cookbook files this run executes.
+   *
+   * Without a filter: all of them, in the order the directory lists them.
+   *
+   * With one, three rules, each a decision:
+   *
+   *   1. **A cookbook is selected WHOLE.** The expression is matched against
+   *      the `operation` of every step, and a cookbook holding one match runs
+   *      entirely. Running only the matching steps would be a different
+   *      cookbook: a later step reads what an earlier one wrote, and the format
+   *      makes that explicit through `depends_on`
+   *      (api/docs/biz/40-cookbooks/variable-references.md).
+   *   2. **A file this method cannot read is never filtered OUT.** Selection
+   *      reads JSON; a file that does not parse, or whose steps are not the
+   *      shape the format requires, is kept and fails in the run where the
+   *      format gate reports it by name. A filter that quietly dropped
+   *      unreadable cookbooks would be a way to walk past that gate
+   *      (`automation-gates.md` §1.5).
+   *   3. **A filter matching nothing is an error**, not an empty pass. A run
+   *      that executes zero cookbooks and reports success is the silent gate of
+   *      `automation-gates.md` §5; the message names the operations the
+   *      directory actually runs, so the fix needs no second command.
+   *
+   * @param {string} cookbooksDir directory being run
+   * @param {string[]} files every `.json` in it
+   * @param {string|undefined} operation the regular expression, or undefined
+   * @returns {string[]} the files to run
+   */
+  _selectCookbooks(cookbooksDir, files, operation) {
+    if (operation === undefined) return files;
+
+    let pattern;
+    try {
+      pattern = new RegExp(operation);
+    } catch (error) {
+      throw new Error(`[CookbookTestRunner] Invalid --operation expression ${JSON.stringify(operation)} - `
+        + `Expected a JavaScript regular expression. Fix: correct it (${error.message}).`, { cause: error });
+    }
+
+    const operationsSeen = new Set();
+    const selected = files.filter((file) => {
+      const operations = this._operationsOf(path.join(cookbooksDir, file));
+      if (operations === null) return true;
+      for (const name of operations) operationsSeen.add(name);
+      return operations.some((name) => pattern.test(name));
+    });
+
+    if (selected.length === 0) {
+      const known = [...operationsSeen].sort().join(', ') || '(none declared)';
+      throw new Error(`[CookbookTestRunner] No cookbook matches --operation ${JSON.stringify(operation)} - `
+        + `Expected a JavaScript regular expression matching one of the operations these cookbooks run: `
+        + `${known}. Fix: correct the expression, or run without --operation.`);
+    }
+
+    return selected;
+  }
+
+  /**
+   * The operations one cookbook file runs, or `null` when the file cannot be
+   * read as a cookbook at all — which is rule 2 above: unreadable is not
+   * "does not match", it is "runs and reports itself".
+   *
+   * @param {string} cookbookPath absolute path
+   * @returns {string[]|null}
+   */
+  _operationsOf(cookbookPath) {
+    try {
+      const cookbook = JSON.parse(fs.readFileSync(cookbookPath, 'utf8'));
+      return readCookbookSteps(cookbook.steps)
+        .map((step) => step && step.operation)
+        .filter((name) => typeof name === 'string' && name.length > 0);
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Execute single step
    */
-  async executeStep(step, testConfig, stepIndex = 0) {
+  async executeStep(step, testConfig, stepIndex = 0, cookbookDefaults = null) {
     const startTime = Date.now();
 
     // ONE label for this step, resolved once. `step.id` alone was undefined for
@@ -291,7 +424,15 @@ class CookbookTestRunner {
       // biz-property incident wrote into the live tenant at every restart.
       // Values arrive already validated as integers, so ctx matches the
       // production ContextBuilder for handlers checking Number.isInteger().
-      const { tenant_id: validationTenantId, workspace_id: validationWorkspaceId } = getTestNamespace();
+      const { tenant_id: validationTenantId, workspace_id: envWorkspaceId } = getTestNamespace();
+
+      // The WORKSPACE, unlike the tenant, is the cookbook author's to choose.
+      const validationWorkspaceId = this._resolveStepWorkspaceId({
+        step,
+        stepLabel,
+        cookbookDefaults,
+        envWorkspaceId
+      });
 
       // Resolve operation spec from operations.json — always returns
       // { modulePath, exportName } (v3 handler dispatch is the only mode).
@@ -332,6 +473,66 @@ class CookbookTestRunner {
     return result;
   }
 
+  /**
+   * The workspace THIS step runs in.
+   *
+   * TWO LEVELS, and the rule that orders them is not this file's: it belongs to
+   * `.claude/rules/workspace-architecture.md` and its single implementation on
+   * the invocation path is
+   * `@onlineapps/conn-orch-orchestrator` → `WorkflowOrchestrator._resolveStepWorkspaceId`
+   * (d.332). A per-step `workspace_id` overrides `defaults.workspace_id` for that
+   * step and for no other; it is read here, per step, so it can never leak into
+   * the next one. This runner CITES that rule rather than importing it: the
+   * package depends on `@onlineapps/logger-contract` and
+   * `@onlineapps/service-validator-core` and on nothing that owns cookbook
+   * semantics, and the third term below is Tier-1's alone, so a shared body would
+   * have to be parameterised to say less than either caller means.
+   *
+   * THE THIRD TERM — the platform namespace from the environment — is what a
+   * cookbook that declares no workspace gets, which is exactly what every such
+   * cookbook got before this method existed. It is a precedence chain over two
+   * DECLARED sources, not a fallback for a missing one: the env value is itself
+   * required (`getTestNamespace()` throws when it is absent), and 32 of the 44
+   * cookbooks in the eight live biz repositories declare no workspace at all
+   * (measured 2026-09-14), so refusing here would fail the boot of six services
+   * the day the rule lands — `automation-gates.md` §3, a gate lands WITH
+   * compliance. The orchestrator reached the same conclusion for the same reason
+   * (d.332): "missing both → error" holds where the scope of the operation is
+   * known, and at boot it is not.
+   *
+   * WHAT A DECLARED VALUE STILL PASSES: `assertWorkspaceId`, the boundary owner
+   * in `utils/testNamespace.js`. A cookbook value that is not an id is refused,
+   * naming the key that carries it — never swapped for the environment value,
+   * which would hide the misconfiguration (architecture-principles.md §3). The
+   * tenant is not resolved here at all: it stays `getTestNamespace()`'s, so no
+   * cookbook can move the boot probe out of an allowed environment class
+   * (api/docs/standards/tenant-allocation.md § Enforcement).
+   *
+   * @param {Object} params
+   * @param {Object} params.step - the cookbook step, possibly carrying `workspace_id`
+   * @param {string} params.stepLabel - the step's name for messages (utils/stepFailure)
+   * @param {Object|null} params.cookbookDefaults - the cookbook's `defaults` block
+   * @param {number} params.envWorkspaceId - the platform namespace workspace
+   * @returns {number} the workspace id for this step
+   */
+  _resolveStepWorkspaceId({ step, stepLabel, cookbookDefaults, envWorkspaceId }) {
+    if (step && step.workspace_id !== undefined) {
+      return assertWorkspaceId(step.workspace_id, {
+        purpose: `cookbook step "${stepLabel}" workspace_id`,
+        setBy: 'in the cookbook'
+      });
+    }
+
+    if (cookbookDefaults && cookbookDefaults.workspace_id !== undefined) {
+      return assertWorkspaceId(cookbookDefaults.workspace_id, {
+        purpose: 'cookbook defaults.workspace_id',
+        setBy: 'in the cookbook'
+      });
+    }
+
+    return envWorkspaceId;
+  }
+
   /**
    * Handler dispatch: require handler module, build minimal real ctx, call
    * handler(input, ctx). Mirrors the production ContextBuilder shape
@@ -395,16 +596,12 @@ class CookbookTestRunner {
     };
     result.request = request;
 
-    let handlerFn;
-    try {
-      const mod = require(spec.modulePath);
-      handlerFn = mod[spec.exportName];
-      if (typeof handlerFn !== 'function') {
-        throw new Error(`[CookbookTestRunner] Handler ${spec.exportName} not exported from ${spec.modulePath}`);
-      }
-    } catch (error) {
-      throw new Error(`[CookbookTestRunner] Failed to load handler ${spec.exportName} from ${spec.modulePath}: ${error.message}`);
-    }
+    // The module was required and the export checked by `resolveOperation`,
+    // through `utils/handlerRef` — the same rule production dispatches by.
+    // Requiring it a second time here was the other half of the duplicated
+    // resolution, and it reported a failure the resolution had already ruled
+    // out.
+    const handlerFn = spec.handler;
 
     let timeoutId;
     const timeoutPromise = new Promise((_, reject) => {
@@ -526,16 +723,45 @@ class CookbookTestRunner {
       }
     }
 
-    // Validate output
-    if (expect.output && result.actual) {
+    // Validate output — whenever the cookbook declares expectations, whether or
+    // not the handler produced anything.
+    //
+    // The guard used to read `expect.output && result.actual`, so a step whose
+    // handler returned nothing skipped every field assertion and was judged on
+    // `status` alone: `validationErrors: []`, a green step over unchecked
+    // expectations (measured by BIZ-pdfgen 2026-08-29; `automation-gates.md`
+    // §5). `validateOutput` already answers correctly for an absent output — a
+    // required field is "missing in output", and an `exists: false` assertion is
+    // SATISFIED by no output — so the guard was what made those two cases
+    // indistinguishable.
+    if (expect.output) {
       const outputErrors = this.validateOutput(expect.output, result.actual);
       errors.push(...outputErrors);
     }
 
-    // Validate error
-    if (expect.error && result.error) {
-      const errorErrors = this.validateError(expect.error, result.error);
-      errors.push(...errorErrors);
+    // Validate error — whenever the cookbook declares one, whether or not the
+    // step actually failed.
+    //
+    // The sister defect of the `expect.output` guard one block up, and the same
+    // shape: `if (expect.error && result.error)` meant a step declaring
+    // `expect.error` over a handler that returned NORMALLY skipped the whole
+    // block. `expect.status` is optional, so a step declaring only `expect.error`
+    // came back with `validationErrors: []` — green, over an expectation nothing
+    // evaluated (`automation-gates.md` §5).
+    //
+    // Here the guard alone cannot be the fix: `validateError` reads `code` and
+    // `message` off the error, and in this case there is no error. The absence
+    // IS the violation, so it gets its own sentence rather than a comparison
+    // against undefined.
+    if (expect.error) {
+      if (result.error) {
+        errors.push(...this.validateError(expect.error, result.error));
+      } else {
+        const declared = expect.error.code === undefined ? '(any)' : expect.error.code;
+        errors.push(`[CookbookTestRunner] Expected error ${declared}, step succeeded - `
+          + 'Expected the handler to throw the declared error; it returned a result instead. '
+          + 'Fix: drive the step to the failing path it declares, or drop expect.error from the step.');
+      }
     }
 
     return {
@@ -545,13 +771,18 @@ class CookbookTestRunner {
   }
 
   /**
-   * Validate output fields
+   * Validate output fields.
+   *
+   * A field name is a dot path into the output — see `resolveOutputField`
+   * above for the two rules it follows (exact key first, objects only) and
+   * for why a descriptor cannot be asserted any other way.
    */
   validateOutput(expected, actual) {
     const errors = [];
 
     for (const [field, expectation] of Object.entries(expected)) {
-      const actualValue = actual[field];
+      const resolved = resolveOutputField(actual, field);
+      const actualValue = resolved.found ? resolved.value : undefined;
 
       // Check existence
       if (expectation.exists !== undefined) {
@@ -568,7 +799,16 @@ class CookbookTestRunner {
       // If field doesn't exist and we're not explicitly checking existence, error
       if (actualValue === undefined || actualValue === null) {
         if (expectation.exists === undefined) {
-          errors.push(`Field ${field}: missing in output`);
+          // A path miss names the first segment that could not be resolved:
+          // "no pdf at all" and "a pdf without a size" are different defects
+          // and get different fixes. A name without a dot keeps the original
+          // wording — its first missing segment is the name itself, and
+          // repeating it would be noise.
+          errors.push(field.includes('.') && resolved.missingSegment !== undefined
+            ? `Field ${field}: missing in output - segment "${resolved.missingSegment}" not found. `
+              + 'Fix: assert a path that exists in the step output '
+              + '(a dot path walks nested objects, not array indices).'
+            : `Field ${field}: missing in output`);
         }
         continue;
       }
@@ -652,8 +892,24 @@ class CookbookTestRunner {
 
   /**
    * Resolve operation spec from operations.json. Returns the handler
-   * dispatch descriptor: { modulePath, exportName, headers }.
-   * Throws if the operation does not declare a v3 `handler`.
+   * dispatch descriptor: { modulePath, exportName, handler } — exactly what the
+   * dispatch reads, and nothing else. It carried `headers: operation.headers ||
+   * {}` until 2026-09-14, which no caller ever read: ctx.headers is built from
+   * `step.headers` (see `_dispatchViaHandler`), which is what the contract
+   * prescribes — api/docs/biz/10-invocation/operation-context.md § ctx.headers
+   * names the STEP, the operations.json rules in `service-validator-core` know
+   * no `headers` field, and not one of the eight live services declares it.
+   * Throws if the operation does not declare a v3 `handler`, or if that
+   * handler does not resolve.
+   *
+   * The ref is read by the shared rule in `utils/handlerRef` — the same one
+   * every shape check in this package uses. This method used to carry its own,
+   * weaker copy: it split on `#` without counting the separators, so
+   * `handlers/v3/good#run#extra` dispatched as `#run`, and it joined the path
+   * onto `<serviceRoot>/src` with no containment check, so `../outside#run`
+   * loaded and ran a module from outside the service source root. Cookbooks run
+   * at every biz service boot, which made that the loosest resolution on the
+   * platform sitting on the hottest path.
    */
   async resolveOperation(serviceName, operationName) {
     const serviceRoot = this._resolveServiceRoot(serviceName);
@@ -662,46 +918,67 @@ class CookbookTestRunner {
     const operationsPath = path.join(serviceRoot, 'config', 'service', 'operations.json');
 
     if (!fs.existsSync(operationsPath)) {
-      throw new Error(`Operations file not found for service: ${serviceName} (expected config/service/operations.json)`);
+      throw new Error(`[CookbookTestRunner] Operations file not found for service: ${serviceName} `
+        + `(expected config/service/operations.json) - Expected the declaration every v3 service ships. `
+        + `Fix: create ${operationsPath} (api/docs/biz/30-operations/schema-v3.md § File shape).`);
     }
 
     const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf8'));
     const operation = operations.operations && operations.operations[operationName];
 
     if (!operation) {
-      throw new Error(`Operation not found: ${operationName}`);
+      throw new Error(`[CookbookTestRunner] Operation not found: ${operationName} - Expected a key of `
+        + `that name under "operations" in ${operationsPath}. Fix: declare the operation there, or `
+        + 'correct the operation name the cookbook step asks for.');
     }
 
     if (!operation.handler) {
       throw new Error(`[CookbookTestRunner] Operation ${serviceName}.${operationName} in ${operationsPath} is missing required v3 field "handler" ("path#exportName"). Fix: declare handler in operations.json per RFC §5.3.`);
     }
 
-    const [modRel, exportName] = String(operation.handler).split('#');
-    if (!modRel || !exportName) {
-      throw new Error(`[CookbookTestRunner] Invalid handler spec "${operation.handler}" for ${serviceName}.${operationName}; expected "path#exportName"`);
-    }
-    const modulePath = require.resolve(path.join(serviceRoot, 'src', modRel));
+    parseHandlerRef(operation.handler);
+    const { modulePath, exportName, handler } = resolveHandlerModule({
+      serviceRoot,
+      handlerRef: operation.handler
+    });
+
     return {
       modulePath,
       exportName,
-      headers: operation.headers || {}
+      handler
     };
   }
 
   /**
-   * Resolve filesystem root for a service. The default resolver assumes
-   * every cookbook step targets the runner's own service (this.servicePath).
-   * Callers that need cross-service dispatch can subclass and override.
+   * Resolve the filesystem root for a `step.service`.
+   *
+   * `_servicePathByName` is the ONLY source: the constructor registers the
+   * primary service under the name it was constructed with, and
+   * `setServicePath` adds every other one. A name that is in neither is an
+   * error, never a guess.
+   *
+   * Until 2026-09-08 an unknown name fell back to `this.servicePath` on the
+   * comment "cookbooks may reference this.serviceName under a different
+   * alias". No such alias exists in the data — measured across the eight live
+   * business repositories, all 37 cookbook steps name their own
+   * `package.json` name, which is exactly what `scripts/run-pre-validation.js`
+   * passes as `serviceName`. What the fallback actually absorbed was a typo:
+   * `"servcie": "biz-hello"` ran biz-hello's handler and reported PASS, so
+   * Tier-1 validated a cookbook the production WorkflowOrchestrator would
+   * route somewhere else entirely. That is a fallback masking bad input
+   * (architecture-principles.md §3), resolved late instead of refused at the
+   * gate (§4).
    */
   _resolveServiceRoot(serviceName) {
     if (this._servicePathByName.has(serviceName)) {
       return this._servicePathByName.get(serviceName);
     }
-    if (!this.servicePath) {
-      throw new Error(`[CookbookTestRunner] No servicePath known for ${serviceName}; construct with servicePath or register via setServicePath(name, path)`);
-    }
-    // Cookbooks may reference this.serviceName under a different alias.
-    return this.servicePath;
+
+    const registered = [...this._servicePathByName.keys()];
+    const known = registered.length > 0 ? registered.join(', ') : '(none registered)';
+    throw new Error(`[CookbookTestRunner] Unknown step.service "${serviceName}" - Expected one of: `
+      + `${known}. Fix: fix the cookbook's step.service, or register the service `
+      + 'via setServicePath(name, path).');
   }
 
   /**
@@ -720,7 +997,8 @@ class CookbookTestRunner {
    */
   loadCookbook(cookbookPath) {
     if (!fs.existsSync(cookbookPath)) {
-      throw new Error(`Cookbook not found: ${cookbookPath}`);
+      throw new Error(`[CookbookTestRunner] Cookbook not found: ${cookbookPath} - Expected a readable `
+        + 'cookbook file at that path. Fix: create it, or correct the path the caller passed.');
     }
 
     const content = fs.readFileSync(cookbookPath, 'utf8');
@@ -733,20 +1011,16 @@ class CookbookTestRunner {
     }
   }
 
-  /**
-   * Normalize steps to array format
-   * Supports V1 (steps as array) and V2 (steps as object keyed by step_id)
-   */
-  normalizeSteps(steps) {
-    // The rule lives in utils/cookbookFormat — the same owner
-    // CookbookTestUtils.validateCookbook now reads, so the two entry points
-    // cannot disagree about what a cookbook's steps are.
-    return normalizeCookbookSteps(steps);
-  }
-
   /**
    * Validate cookbook format
-   * Supports both V1 (steps as array) and V2 (steps as object) formats
+   *
+   * `steps` is an ARRAY of step objects — the only shape the format allows
+   * (owner confirmation `cookbook-steps-shape` 001 of 2026-09-05). The runner
+   * used to accept an object keyed by `step_id` and convert it, which made this
+   * gate pass cookbooks the production WorkflowOrchestrator threw on. The shape
+   * rule itself lives in `utils/cookbookFormat.readCookbookSteps`, the same
+   * owner `CookbookTestUtils.validateCookbook` reads, so the two entry points
+   * cannot disagree about what a cookbook's steps are.
    *
    * The format-version check is FIRST and unconditional. Until 2026-08-27 it
    * lived only in `CookbookTestUtils.validateCookbook`, reachable exclusively
@@ -767,20 +1041,31 @@ class CookbookTestRunner {
       throw new Error(`[CookbookTestRunner] ${versionProblem}`);
     }
 
-    if (!cookbook.steps || (typeof cookbook.steps !== 'object' && !Array.isArray(cookbook.steps))) {
-      throw new Error('Cookbook must have steps (array or object)');
+    if (cookbook.steps === undefined || cookbook.steps === null) {
+      throw new Error('[CookbookTestRunner] Cookbook has no steps - Expected "steps": [ … ] with at '
+        + 'least one step object carrying "step_id". '
+        + 'Fix: add the steps array (api/docs/biz/40-cookbooks/format.md § Required fields).');
     }
 
-    // Normalize steps to array for validation
-    const stepsArray = this.normalizeSteps(cookbook.steps);
+    // Throws unless `steps` is the array the format requires.
+    const stepsArray = readCookbookSteps(cookbook.steps);
 
     if (stepsArray.length === 0) {
-      throw new Error('Cookbook must have at least one step');
+      throw new Error('[CookbookTestRunner] Cookbook must have at least one step - Expected a non-empty '
+        + 'steps array. Fix: add at least one step (api/docs/biz/40-cookbooks/format.md § Required fields).');
     }
 
     for (const step of stepsArray) {
-      if (!step.service) throw new Error(`Step ${step.step_id || 'unknown'} must have service`);
-      if (!step.operation) throw new Error(`Step ${step.step_id || 'unknown'} must have operation`);
+      if (!step.service) {
+        throw new Error(`[CookbookTestRunner] Step ${step.step_id || 'unknown'} must have service - `
+          + 'Expected the name of the service that runs the step. Fix: add "service" to that step '
+          + '(api/docs/biz/40-cookbooks/format.md § Step definition).');
+      }
+      if (!step.operation) {
+        throw new Error(`[CookbookTestRunner] Step ${step.step_id || 'unknown'} must have operation - `
+          + 'Expected the operation that service exposes. Fix: add "operation" to that step '
+          + '(api/docs/biz/40-cookbooks/format.md § Step definition).');
+      }
     }
 
     return true;
@@ -788,10 +1073,9 @@ class CookbookTestRunner {
 
   /**
    * Check if cookbook has expect clauses
-   * Supports both V1 (array) and V2 (object) step formats
    */
   hasExpectClauses(cookbook) {
-    const stepsArray = this.normalizeSteps(cookbook.steps);
+    const stepsArray = readCookbookSteps(cookbook.steps);
     return stepsArray.some(step => step.expect !== undefined);
   }
 
@@ -806,12 +1090,35 @@ class CookbookTestRunner {
    * Reset results
    */
   resetResults() {
-    this.results = {
+    this.results = this._emptyResults();
+  }
+
+  /**
+   * The aggregate a run starts from — one definition, read by the constructor
+   * and by `resetResults()`. Two copies is how `cookbooks` would end up counted
+   * in one of them and not the other.
+   *
+   * `total`/`passed`/`failed` count STEPS and always did. `cookbooks` counts
+   * cookbooks, and it exists because the boot line said "Cookbook tests: X/Y"
+   * about step numbers: three cookbooks of one step each read as "3/3", so the
+   * day one of them gained a second step the number rose without a cookbook
+   * being added (measured by BIZ-converter 2026-08-27). Both facts are real and
+   * they answer different questions — how much was exercised, and how much
+   * passed — so both are counted and the line names which is which
+   * (`automation-gates.md` §5: a label that disagrees with its measurement is a
+   * false guarantee, not untidiness).
+   *
+   * @returns {{total: number, passed: number, failed: number, duration: number,
+   *            steps: Array, cookbooks: {total: number, passed: number, failed: number}}}
+   */
+  _emptyResults() {
+    return {
       total: 0,
       passed: 0,
       failed: 0,
       duration: 0,
-      steps: []
+      steps: [],
+      cookbooks: { total: 0, passed: 0, failed: 0 }
     };
   }
 }