@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/manifests/biz-service.manifest.json

@@ -49,6 +49,7 @@
         "check": "template-block",
         "path": "init.sh",
         "block": "oa-deps-guard v1",
+        "insert_after_function": "oa_npm_install",
         "from": { "package": "templates/business-service/init.sh", "text": true },
         "severity": "deploy",
         "owner": "BIZ-general",
@@ -100,14 +101,14 @@
         "from": { "package": "templates/business-service/gitignore", "text": true },
         "severity": "deploy",
         "owner": "BIZ-general",
-        "why": "Dockerfile line COPY . . takes everything .dockerignore does not exclude, and being ignored by git excludes nothing: measured by BIZ-hello 2026-09-11, a LOCAL production image of hello came to 6.6 GB - 5.2 GB of it logs/ - and carried config/env-active/*.env with DB_PASSWORD, JWT_SECRET, the MinIO keys and RABBITMQ_URL. A CI image is clean by accident, because a fresh checkout has no ignored file to copy, so the defect is invisible exactly where the image is built. The entries are DERIVED from the declaration .gitignore already reads rather than written a second time (change-discipline.md \u00a7 One rail per concern), and translated: a slash-less .gitignore pattern matches at every depth while a .dockerignore one is matched from the context root, so *.log there would catch debug.log and not logs/debug.log. The criterion is a comparison and never a list of directories - the files in /app of an image built from the working tree, node_modules aside, are the files of an image built from git archive HEAD",
+        "why": "Dockerfile line COPY . . takes everything .dockerignore does not exclude, and being ignored by git excludes nothing: measured by BIZ-hello 2026-09-11, a LOCAL production image of hello came to 6.6 GB - 5.2 GB of it logs/ - and carried config/env-active/*.env with DB_PASSWORD, JWT_SECRET, the MinIO keys and RABBITMQ_URL. A CI image is clean by accident, because a fresh checkout has no ignored file to copy, so the defect is invisible exactly where the image is built. The entries are DERIVED from the declaration .gitignore already reads rather than written a second time (change-discipline.md \u00a7 One rail per concern), and translated: a slash-less .gitignore pattern matches at every depth while a .dockerignore one is matched from the context root, so *.log there would catch debug.log and not logs/debug.log. The criterion is a comparison and never a list of directories - the files in /app of an image built from the working tree, node_modules aside, are the files of an image built from git archive HEAD MINUS the test tree (d.560): tests belong in the repository and never in the artefact that runs, which is the decision the library uniform makes one manifest over as L-PACK-TESTS. The single exception is tests/cookbooks, and it is not a test at all but a declaration the RUNTIME reads - Tier-1 of the boot runs those cookbooks at phase 0.2, and an image without the directory measures zero of them, so ValidationProofGenerator refuses the proof as NO_TESTS and the service never starts",
         "fix": "npx oa-sync-template .dockerignore --target . - it writes the derived entries under one labelled block and rewrites nothing this repository wrote",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a72"
       }
     ],
     "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",
@@ -138,9 +139,9 @@
         "from": { "package": "templates/business-service/.gitlab-ci.yml", "text": true },
         "severity": "deploy",
         "owner": "BIZ-general",
-        "why": "the platform half of a biz pipeline belongs to the platform, not to the service: it builds the same way, identifies the image by the FULL commit sha (R5), hands the deploy the digest CI itself pushed (R1/R2), and since confirmation 008 it runs the uniform gate before the SSH step - a service that edits any of that edits the gate that judges it. It is a BLOCK and not the whole file because the other half is genuinely the service's. Measured over the eight repositories on 2026-09-11: the template is 151 lines and 7 root keys, the services 176 to 198 lines and 9, and every difference is theirs - the test job that stands up MariaDB, Redis and RabbitMQ as service containers, runs five ci:gate:* steps and publishes ci/integration-signal.json, plus workflow: and verify-installation-contract:. Which database and which gates an integration needs is a fact about the service. A whole-file fix would have deleted all of it and left eight integration tiers running against no database, which is a finding nobody can carry out (automation-gates.md §3, last bullet; controller finding 20)",
+        "why": "the platform half of a biz pipeline belongs to the platform, not to the service: it builds the same way, identifies the image by the FULL commit sha (R5), hands the deploy the digest CI itself pushed (R1/R2), and runs the uniform twice - continuously, in job validate-uniform on every pipeline including the devel mirror (confirmation 010), and again before the SSH step as the binding last instance (confirmation 008). A service that edits any of that edits the gate that judges it. It is a BLOCK and not the whole file because the other half is genuinely the service's: which database, which ci:gate:* steps and which artefacts its integration needs is a fact about the service, and so - since the block cannot own it - is whether that job's own rules name the devel branch the block's jobs now name. Measured over the eight repositories on 2026-09-11: the template was 151 lines and 7 root keys, the services 176 to 198 lines and 9, and every difference was theirs - the test job that stands up MariaDB, Redis and RabbitMQ as service containers, runs five ci:gate:* steps and publishes ci/integration-signal.json, plus workflow: and verify-installation-contract:. Of those two the first became the block's in d.251b; the second is the template's no longer - d.470 stopped declaring it, its work moved into the rows G-SETUP, D-DB-PACKAGE and D-DB-HEADERS that the uniform gate runs, and each repository keeps its own copy until its release retires it (d.320). A whole-file fix would have deleted all of it and left eight integration tiers running against no database, which is a finding nobody can carry out (automation-gates.md §3, last bullet; controller finding 20)",
         "fix": "npx oa-sync-template .gitlab-ci.yml --target .",
-        "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a7 Confirmation 20260910-biz-service-manifest-008"
+        "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a7 Confirmation 20260916-biz-service-manifest-010"
       },
       {
         "id": "G-PROD-IMAGE",
@@ -293,6 +294,17 @@
         "fix": "add scripts[\"test:integration:container\"] wrapping the runner this repository declares",
         "doc": "api/docs/governance/confirmations/biz-test-container.md"
       },
+      {
+        "id": "S-UNIT-C",
+        "check": "script-body",
+        "name": "test:unit:container",
+        "body": "docker compose run --rm ${runner} npm run test:unit",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "the unit suite is the measured reason the runner exists (biz-test-container 001: unit 341 MiB beside a 96 MiB service in a 384 MB budget, SIGKILL for both), so it has a wrapper like every other suite; the NAME says which suite runs, the way test:all:container and test:integration:container do, and the five repositories reaching it through test:container were a second spelling of one rail that script-body cannot see",
+        "fix": "rename scripts[\"test:container\"] to scripts[\"test:unit:container\"], wrapping the runner this repository declares",
+        "doc": "api/docs/governance/confirmations/biz-test-container.md"
+      },
       {
         "id": "S-COOKBOOKS",
         "check": "script-body",
@@ -304,6 +316,17 @@
         "why": "the cookbook run is the library's command; a per-service copy of it drifts from the library that owns the dispatch",
         "fix": "set scripts[\"test:cookbooks\"] to the library command and delete the per-service script",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md §5"
+      },
+      {
+        "id": "S-COOK-C",
+        "check": "script-body",
+        "name": "test:cookbooks:container",
+        "body": "docker compose run --rm ${runner} npm run test:cookbooks",
+        "severity": "deploy",
+        "owner": "BIZ-general",
+        "why": "the cookbook run dispatches real handlers and reads TESTING_TENANT_ID / TESTING_WORKSPACE_ID, which only the runner has from env_file; without the wrapper the documented path to it is a host command that fails on missing env rather than on the cookbook",
+        "fix": "add scripts[\"test:cookbooks:container\"] wrapping the runner this repository declares",
+        "doc": "api/docs/governance/confirmations/biz-test-container.md"
       }
     ],
     "forbidden": [
@@ -420,10 +443,10 @@
         "id": "G-SHARED-ENV",
         "check": "shared-env-generated",
         "path": "config/env-templates/shared.env",
-        "from": { "package": "templates/business-service/config/env-templates/shared.env", "text": true },
+        "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 still api/config/shared-env.json: what this row reads is the render this package carries, kept equal to that manifest by the packaged template's own gate, so the row also answers inside a service container, where api/config/ is not there",
+        "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",
         "fix": "npx oa-sync-template shared-env --target .",
         "doc": "api/docs/governance/confirmations/biz-service-manifest.md \u00a718"
       },
@@ -474,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",
@@ -564,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": "9.0.0",
+  "version": "11.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"
@@ -28,8 +28,9 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
+    "@onlineapps/cookbook-core": "6.0.0",
     "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/service-validator-core": "2.0.1"
+    "@onlineapps/service-validator-core": "2.1.0"
   },
   "devDependencies": {
     "jest": "^29.5.0"

package/src/CookbookTestRunner.js

@@ -3,13 +3,15 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const MockMQClient = require('./mocks/MockMQClient');
-const MockRegistry = require('./mocks/MockRegistry');
 const { resolveHeaders } = require('./utils/resolveHeaders');
 const { checkCookbookFormatVersion, readCookbookSteps } = require('./utils/cookbookFormat');
 const { getTestNamespace, assertWorkspaceId } = require('./utils/testNamespace');
-const { describeStepFailure, describeStepIdentity } = require('./utils/stepFailure');
+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');
 
 /**
@@ -76,7 +78,14 @@ function resolveOutputField(container, fieldPath) {
 }
 
 /**
- * CookbookTestRunner — executes cookbook tests offline with mocked infrastructure.
+ * CookbookTestRunner — executes cookbook tests in this process, without a transport.
+ *
+ * There is no infrastructure double. `mockInfrastructure` built a MockMQClient
+ * and a MockRegistry for the days when a step was dispatched through a
+ * transport; since v3 in-process dispatch there is nothing for them to stand in
+ * for, nothing read them, and the database a handler reaches is the SERVICE's
+ * real one. The option is retired and refused by name in the constructor and in
+ * a cookbook's `test` block — see README § Pre-validation runs in-process.
  *
  * Dispatch is exclusively v3 handler-registry: each operation MUST declare
  * `handler: "path#exportName"` in operations.json. The runner loads the
@@ -109,9 +118,20 @@ class CookbookTestRunner {
     // docs/governance/confirmations/connector-logger-contract.md 001.
     assertLogger('CookbookTestRunner', options.logger, 'the runner writes where the service writes');
 
+    // A RETIRED option is refused, never ignored: a caller that still writes it
+    // believes it buys something, and silently doing nothing is the implicit
+    // behaviour `.claude/rules/architecture-principles.md` §8 forbids. Both
+    // values are refused — `false` asked for the same absent mechanism as
+    // `true`. Why the concept went: `tests/unit/mockInfrastructureRetired.test.js`.
+    if (options.mockInfrastructure !== undefined) {
+      throw new Error('[CookbookTestRunner] mockInfrastructure is not an option - a cookbook step is '
+        + 'dispatched in-process against the service\'s own v3 handler, with no transport to '
+        + 'stand in for; the database a handler reaches is the real one. '
+        + 'Fix: drop mockInfrastructure from the constructor options.');
+    }
+
     this.serviceName = options.serviceName;
     this.servicePath = options.servicePath;
-    this.mockInfrastructure = options.mockInfrastructure !== false;
     this.timeout = options.timeout;
     if (!this.timeout || typeof this.timeout !== 'number' || this.timeout <= 0) {
       throw new Error('[CookbookTestRunner] timeout is required — Expected positive number (ms)');
@@ -122,12 +142,6 @@ class CookbookTestRunner {
       this._servicePathByName.set(this.serviceName, this.servicePath);
     }
 
-    // Initialize mocked infrastructure
-    if (this.mockInfrastructure) {
-      this.mqClient = new MockMQClient();
-      this.registry = new MockRegistry();
-    }
-
     // Test results
     this.results = this._emptyResults();
   }
@@ -156,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 });
@@ -178,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).
@@ -278,6 +314,13 @@ class CookbookTestRunner {
         this.results.cookbooks.total += 1;
         this.results.cookbooks.failed += 1;
         this.results.steps.push({
+          // WHAT this record is, said here rather than inferred downstream from
+          // the absence of `step_id`. It is not a step: this cookbook produced
+          // none. Every consumer of `results.steps` reads the field
+          // (`utils/stepFailure.js`), and until d.516b the aggregate error list
+          // called this `step "step #1"` — a step that does not exist
+          // (`.claude/rules/architecture-principles.md` §8).
+          kind: KIND_COOKBOOK_LOAD_FAILURE,
           cookbook: file,
           passed: false,
           error: error.message
@@ -366,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
@@ -380,6 +435,9 @@ class CookbookTestRunner {
     this.logger.info(`Executing step: ${stepLabel} (${step.operation})`);
 
     const result = {
+      // The other half of the pair: this record IS a step, and says so beside
+      // the cookbook-load failure that is not (d.516b).
+      kind: KIND_STEP,
       // The identifier the format requires, plus the position, so the aggregate
       // error list can name the step without re-deriving anything. `id` was
       // emitted alongside it until 2026-08-30; one thing, one name.
@@ -438,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,
@@ -540,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.
@@ -556,6 +622,18 @@ class CookbookTestRunner {
       correlation_id: correlationId,
       person_id: personId,
       operation_name: step.operation,
+      // WHICH STEP is running, not merely which operation. Production
+      // `OperationContext` carries it among its 16 fields
+      // (`@onlineapps/service-wrapper` src/OperationContext.js), and a handler
+      // that stores a file cannot do without it:
+      // `@onlineapps/conn-orch-content-resolver` keys every stored object on
+      // `content/<workflow_id>/<step_id>` and refuses to invent either half.
+      // Tier-1 left it out, so a service moving off `operation_name` onto
+      // `ctx.step_id` passed in production and died in ServiceWrapper phase 0.2
+      // (BIZ-pdfgen, measured 2026-09-16 against 9.0.0 and HEAD). It is per
+      // STEP on purpose: one cookbook may call the same operation twice, and
+      // those two runs must not share a storage prefix.
+      step_id: step.step_id,
       service_name: step.service,
       db: null,
       cache: null,
@@ -585,13 +663,14 @@ 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,
         workflow_id: ctx.workflow_id,
         correlation_id: ctx.correlation_id,
-        person_id: ctx.person_id
+        person_id: ctx.person_id,
+        step_id: ctx.step_id
       }
     };
     result.request = request;
@@ -621,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) {
@@ -1041,6 +1120,22 @@ class CookbookTestRunner {
       throw new Error(`[CookbookTestRunner] ${versionProblem}`);
     }
 
+    // The retired option, in the other place a caller could still write it. The
+    // cookbook schema admits additional properties inside `test`, so nothing
+    // refuses the key at load time — and a key nobody reads taught every reader
+    // that a cookbook chooses its own infrastructure, which it never did
+    // (`change-discipline.md` § Removing something removes its declaration).
+    // Refused BY NAME rather than dropped in silence, for the reason the
+    // constructor refuses it one screen up.
+    if (cookbook.test && typeof cookbook.test === 'object'
+        && cookbook.test.mockInfrastructure !== undefined) {
+      throw new Error('[CookbookTestRunner] Cookbook declares test.mockInfrastructure - the option is '
+        + 'retired; a cookbook never chose its own infrastructure and the runner dispatches '
+        + 'in-process against the real service. '
+        + 'Fix: remove "mockInfrastructure" from the cookbook\'s "test" block '
+        + '(api/docs/biz/40-cookbooks/format.md § Optional top-level fields).');
+    }
+
     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". '
@@ -1055,18 +1150,35 @@ class CookbookTestRunner {
         + 'steps array. Fix: add at least one step (api/docs/biz/40-cookbooks/format.md § Required fields).');
     }
 
-    for (const step of stepsArray) {
+    // The three fields `@onlineapps/cookbook-core` 5.0.0 requires of a task step
+    // beyond `type` (`schemas/cookbook.v2.schema.json`
+    // definitions.TaskStep.required). `step_id` comes FIRST, because it is what
+    // the other two messages name the step by: until d.516b this guard checked
+    // only the last two and wrote `Step ${step.step_id || 'unknown'}`, so a
+    // cookbook missing the field the whole format addresses steps by was
+    // accepted here and its diagnostics said `Step unknown`. A stand-in name is
+    // the fallback `.claude/rules/architecture-principles.md` §3 forbids; with
+    // the field required, the case it stood in for cannot occur.
+    stepsArray.forEach((step, index) => {
+      const position = index + 1;
+      if (typeof step.step_id !== 'string' || step.step_id.length === 0) {
+        throw new Error(`[CookbookTestRunner] Step #${position} has no step_id - every step of a v2.1 `
+          + 'cookbook is addressed by its own step_id (@onlineapps/cookbook-core '
+          + 'schemas/cookbook.v2.schema.json definitions.TaskStep.required). '
+          + `Fix: add "step_id" to step #${position} `
+          + '(api/docs/biz/40-cookbooks/format.md § Required fields).');
+      }
       if (!step.service) {
-        throw new Error(`[CookbookTestRunner] Step ${step.step_id || 'unknown'} must have service - `
+        throw new Error(`[CookbookTestRunner] Step ${step.step_id} 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 - `
+        throw new Error(`[CookbookTestRunner] Step ${step.step_id} 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;
   }