@onlineapps/conn-orch-validator 9.0.0 → 10.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,7 +101,7 @@
         "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"
       }
@@ -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"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "oa": {
     "category": "orchestration"
@@ -29,7 +29,7 @@
   "license": "PROPRIETARY",
   "dependencies": {
     "@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,12 +3,12 @@
 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 { assertLogger } = require('@onlineapps/logger-contract');
 
@@ -76,7 +76,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 +116,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 +140,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();
   }
@@ -278,6 +290,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
@@ -380,6 +399,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.
@@ -556,6 +578,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,
@@ -591,7 +625,8 @@ class CookbookTestRunner {
         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;
@@ -1041,6 +1076,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 +1106,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;
   }

package/src/ValidationOrchestrator.js

@@ -8,10 +8,13 @@ const { normalizeEnvDeclaration, collectEnvCoverage, verifyEnvPresence } = requi
 // called. It verified a cached proof before booting; the proof cache was
 // removed (see validate()) and the verifier's last call site went with it,
 // leaving a binding whose only remaining effect was to tell a reader that this
-// class still checks proofs. `ValidationProofCodec` stays — finalizeResults()
-// encodes the proof it writes.
-const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
+// class still checks proofs. `ValidationProofCodec` went the same way in d.524:
+// finalizeResults() no longer encodes a proof of its own — it asks
+// `ValidationProofGenerator`, which is the one author of one, and the codec is
+// that generator's business.
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
+const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
+const { VALIDATOR_VERSION } = require('./validatorIdentity');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const { describeStepFailureWithContext } = require('./utils/stepFailure');
 const CookbookTestRunner = require('./CookbookTestRunner');
@@ -38,6 +41,41 @@ const { buildDeployabilitySignal, writeDeployabilitySignal } = require('./manife
  */
 const CONFIG_STEP_ROWS = Object.freeze(['C-SERVICE', 'C-OPS', 'C-CONTRACT']);
 
+/**
+ * One number a step MEASURED — or a refusal.
+ *
+ * The run's `totalTests`/`passedTests`/`failedTests` used to be summed with
+ * `|| 0`, so a step that measured nothing contributed a zero and the aggregate
+ * could not tell "no tests ran" from "the step did not say". The proof's author
+ * refuses an unmeasured field (`ValidationProofGenerator.readMeasurement`,
+ * d.524), but it never saw one: the fallback had already turned it into a
+ * number. That is `.claude/rules/architecture-principles.md` §3 (No Fallbacks)
+ * standing exactly where §4 wants a refusal, and the far end paid for it —
+ * `ValidationProofCodec.decode()` rejects the resulting proof as NO_TESTS, days
+ * later and nowhere near the cause.
+ *
+ * A measured 0 is untouched: zero failures is the ordinary case. What is
+ * refused is the ABSENCE of a measurement.
+ *
+ * @param {Object} step the step result the aggregate is summing
+ * @param {string} field `total`, `passed` or `failed`
+ * @param {string} stepName the step's name, for the refusal
+ * @returns {number} the measured value
+ */
+function readStepMeasurement(step, field, stepName) {
+  const value = step === null || step === undefined ? undefined : step[field];
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`[ValidationOrchestrator] Missing measurement - step "${stepName}" reported `
+      + `${JSON.stringify(value) === undefined ? 'undefined' : JSON.stringify(value)} for "${field}", `
+      + 'and the run counts measured values only - a zero standing in for an absent measurement is '
+      + 'what makes a proof of nothing look like a passing validation. '
+      + `Fix: return a finite number as "${field}" from step "${stepName}".`);
+  }
+
+  return value;
+}
+
 /**
  * ValidationOrchestrator
  *
@@ -391,9 +429,11 @@ class ValidationOrchestrator {
       // Step 5: Cookbook Tests
       this.logger.info('[ValidationOrchestrator] Step 5/7: Cookbook Tests');
       results.steps.cookbooks = await this.runCookbookTests();
-      results.totalTests += results.steps.cookbooks.total || 0;
-      results.passedTests += results.steps.cookbooks.passed || 0;
-      results.failedTests += results.steps.cookbooks.failed || 0;
+      // Measured values only — see readStepMeasurement() for why `|| 0` here
+      // was the reason the generator's refusal never fired.
+      results.totalTests += readStepMeasurement(results.steps.cookbooks, 'total', 'cookbooks');
+      results.passedTests += readStepMeasurement(results.steps.cookbooks, 'passed', 'cookbooks');
+      results.failedTests += readStepMeasurement(results.steps.cookbooks, 'failed', 'cookbooks');
       if (!results.steps.cookbooks.success) {
         results.success = false;
         results.errors.push(...(results.steps.cookbooks.errors || []));
@@ -773,7 +813,7 @@ class ValidationOrchestrator {
         serviceRoot: this.serviceRoot,
         signal: buildDeployabilitySignal({
           result,
-          validatorVersion: require('../package.json').version
+          validatorVersion: VALIDATOR_VERSION
         })
       });
 
@@ -825,21 +865,34 @@ class ValidationOrchestrator {
       try {
         // Generate validation proof
         const fingerprint = await this.calculateFingerprint();
-        const proof = {
+
+        // Through the generator, which is the ONE author of a proof. Built here
+        // by hand and handed straight to the codec, this proof escaped both of
+        // the generator's refusals: an unmeasured field (`readMeasurement`) and
+        // a run that executed nothing
+        // (`.claude/rules/change-discipline.md` § One rail per concern).
+        //
+        // The numbers reaching it are measured ones: the aggregate above sums
+        // through `readStepMeasurement()`, so an absent measurement fails the
+        // run here rather than arriving as a zero the generator cannot tell
+        // from a real one (d.576b).
+        const generator = new ValidationProofGenerator({
           serviceName: this.serviceName,
-          version: this.serviceVersion,
-          contractFingerprint: fingerprint, // Store contract fingerprint for subsequent starts
-          validator: '@onlineapps/conn-orch-validator',
-          validatorVersion: require('../package.json').version,
-          validatedAt: new Date().toISOString(),
-          testsRun: results.totalTests,
-          testsPassed: results.passedTests,
-          testsFailed: results.failedTests,
-          durationMs: duration
-        };
+          serviceVersion: this.serviceVersion
+        });
 
-        // Encode proof using ValidationProofCodec
-        const encodedProof = ValidationProofCodec.encode(proof);
+        const pkg = this.readServicePackageJson(path.join(this.serviceRoot, 'package.json'));
+
+        const encodedProof = generator.generateProof(
+          {
+            total: results.totalTests,
+            passed: results.passedTests,
+            failed: results.failedTests,
+            duration
+          },
+          pkg.dependencies || {},
+          { contractFingerprint: fingerprint }
+        );
 
         // Save proof to conn-runtime/
         await this.saveProof(encodedProof);

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

@@ -33,6 +33,7 @@ const {
   PLATFORM_TEST_FILE_PATTERN,
 } = require('../utils/testCoverageContract');
 const { runPreValidation } = require('../utils/preValidation');
+const { describeRecordIdentity } = require('../utils/stepFailure');
 const { checkLibCompat, loadLibrarySet } = require('../utils/libCompat');
 const { buildSchema } = require('../utils/setupDatabase');
 
@@ -89,7 +90,7 @@ Commands:
                              contract's closed vocabularies on every live migrations/**/*.sql
                              (archive/ and superseded/ excluded), and each BASELINE manifest
                              naming exactly the files the installer applies, in that order.
-  run-prevalidation          Run the service's cookbooks offline against mocked infrastructure
+  run-prevalidation          Run the service's cookbooks in-process (no transport, real database)
                              and write conn-runtime/validation-proof.json. Replaces the
                              per-service scripts/run-pre-validation.js.
   verify-lib-compat          Compare @onlineapps/* pins against the platform library SSOT (R6).
@@ -382,18 +383,6 @@ async function runVerifyContract(options) {
 }
 
 
-/**
- * Running cookbooks needs `tests/cookbooks/`, `operations.json` and the handler
- * modules — nothing else. This command used to resolve the service's own
- * `@onlineapps/service-wrapper`, run `ConfigLoader.loadAll()` 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 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 on none of them.
- */
 /**
  * End the process with this code, once everything written has left the buffers.
  *
@@ -434,6 +423,27 @@ function exitWhenFlushed(code) {
   done();
 }
 
+/**
+ * What a cookbook run reads, and what it does NOT.
+ *
+ * It reads `tests/cookbooks/`, `config/service/operations.json` and the
+ * service's `package.json`, and it dispatches the service's own v3 handler
+ * modules IN THIS PROCESS. So it needs whatever those handlers need: a handler
+ * that reaches its schema opens the service's real pool here, which is the
+ * subject of `exitWhenFlushed` above. "Nothing else" is what this sentence used
+ * to say, and the paragraph below it said the opposite (d.523).
+ *
+ * What it does not do is load the service CONFIG. This command used to resolve
+ * the service's own `@onlineapps/service-wrapper`, run `ConfigLoader.loadAll()`
+ * 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
+ * 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
+ * on none of them.
+ */
 async function runRunPreValidation(options) {
   const outcome = await runPreValidation({
     serviceRoot: path.resolve(options.serviceRoot),
@@ -451,7 +461,11 @@ async function runRunPreValidation(options) {
 
   if (!outcome.ok) {
     for (const step of outcome.failedSteps) {
-      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${step.step_id}: ${step.error}\n`);
+      // The record names itself: `results.steps` carries two kinds and this
+      // line printed `step_id` for both, so a rejected cookbook read as
+      // `undefined` (d.523). The identity comes from the one owner of it,
+      // through `runPreValidation`'s outcome.
+      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${describeRecordIdentity(step)}: ${step.error}\n`);
       for (const validationError of step.validationErrors) {
         process.stderr.write(`[BizCiGate]   * ${validationError}\n`);
       }

package/src/cli/oa-sync-template.js

@@ -11,8 +11,9 @@
  *   * bare paths - the uniform sync of confirmation 001 §3.2. It writes the
  *     files of the manifest classes `identical` and `generated` from the very
  *     `from:` reference those rows already point the conformance CHECK at, and
- *     never touches a file of the `own` class. A row the manifest does not make
- *     renderable is reported NOT RUN by name, never filled from a guess.
+ *     never touches a file of the `own` class. A row that names no `from:`
+ *     reference is not a row of this run — it is a requirement about the
+ *     repository, and `npx oa-validate` is what answers it (d.507).
  *   * `--new <name>` - the whole service tree, from the template that ships
  *     inside this package (001 §2). It is what `api/scripts/add-service.sh
  *     --scaffold` runs; that script keeps the platform facts (the registry
@@ -48,7 +49,7 @@ const {
   SSOT_PIN,
   TEMPLATE_ROOT
 } = require('../sync/serviceTemplate');
-const { planSync, uniformRows } = require('../sync/uniformFiles');
+const { planSync, uniformRows, isSyncRow } = require('../sync/uniformFiles');
 const { loadManifest: loadUniformManifest, DEFAULT_MANIFEST_PATH } = require('../manifest/loadManifest');
 const {
   applyUniformRegion,
@@ -107,10 +108,11 @@ Usage:
   is: generated output, committed for reading (001 §5). --check is the gate.
 
   With bare paths (or none, meaning all of them) the run rewrites the files the
-  manifest declares in the classes "identical" and "generated", from the same
-  reference the conformance check reads. Files of the "own" class - src/**,
-  tests/**, the content of docs/** - are never written. A row the manifest does
-  not make renderable is printed NOT RUN with the reason.
+  manifest declares in the classes "identical" and "generated" that name a
+  "from" reference, from that same reference the conformance check reads. Files
+  of the "own" class - src/**, tests/**, the content of docs/** - are never
+  written. A row naming no reference is a requirement about the repository
+  rather than a file, and npx oa-validate <serviceRoot> is what answers it.
 
   --new <name>        create a service tree from the packaged template
   --into <dir>        where that tree is written; it must not exist yet
@@ -721,9 +723,22 @@ function runSync(options) {
   // The positionals are judged FIRST, against the manifest, and before anything
   // that touches the disk: a mistyped subcommand must be named as what it is,
   // not reported as a missing workspace three steps later.
-  const declared = uniformRows(loadUniformManifest(DEFAULT_MANIFEST_PATH)).map((row) => row.path);
+  const rows = uniformRows(loadUniformManifest(DEFAULT_MANIFEST_PATH));
+  const declared = rows.filter(isSyncRow).map((row) => row.path);
   for (const wanted of options.paths) {
     if (declared.includes(wanted)) continue;
+
+    // A path the uniform DOES declare, as a requirement rather than as a file
+    // this run renders, is refused by what it is and not as a typo: the reader
+    // named a real row, and what they need is the run that answers it.
+    const requirement = rows.find((row) => row.path === wanted);
+    if (requirement !== undefined) {
+      throw new Error(`[oa-sync-template] "${wanted}" is declared by ${requirement.id}, which names no "from" `
+        + 'reference - it is a requirement about the repository, not a file this run renders. '
+        + 'Fix: check it with npx oa-validate <serviceRoot>; the paths this run writes are '
+        + `(${declared.join(', ')}).`);
+    }
+
     throw new Error(`[oa-sync-template] Unknown argument "${wanted}" - it is neither a subcommand this run `
       + `has (${SUBCOMMAND_NAMES.join(', ')}) nor a path the uniform declares (${declared.join(', ')}). `
       + 'Fix: name one of those, or leave the paths out to write them all.');

package/src/cli/oa-validate.js

@@ -433,7 +433,13 @@ function main(argv) {
   }
   const serviceRoot = canonicalRoot(given);
 
-  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
+  // The workspace this SERVICE lies in, not the one this package lies in
+  // (d.540): the copy a service runs is the one it installed, and an installed
+  // copy is part of no checkout — `oa-validate .` inside a complete workspace
+  // printed NOT RESOLVED and reported every workspace row NOT RUN. The root is
+  // the one the caller named, never `process.cwd()`
+  // (`workspaceRoot.js` § The service a run is ABOUT).
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, serviceRoot });
   const result = runManifest({ manifest, serviceRoot, workspaceRoot });
 
   process.stdout.write(options.json ? renderJson(result) : renderReport(result));

package/src/index.js

@@ -12,10 +12,6 @@
  * @see /api/docs/architecture/validator.md (validator architecture)
  */
 
-const MockMQClient = require('./mocks/MockMQClient');
-const MockRegistry = require('./mocks/MockRegistry');
-const MockStorage = require('./mocks/MockStorage');
-
 const CookbookTestUtils = require('./CookbookTestUtils');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
@@ -34,11 +30,16 @@ const ValidationOrchestrator = require('./ValidationOrchestrator');
 
 const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
 
+// No infrastructure doubles are published. `MockMQClient`, `MockRegistry` and
+// `MockStorage` were the furniture of `mockInfrastructure`, retired in d.576:
+// pre-validation dispatches a step in-process against the service's own v3
+// handler, so there is no transport to stand in for, and the database a handler
+// reaches is the real one. `MockRegistry` stays inside the package as the
+// registry stand-in of `helpers/createServiceReadinessTests`, which is a
+// different concern and keeps its own consumer; `MockMQClient` as the double of
+// `tests/unit/RegistrationFlow.test.js`. `MockStorage` had neither, so d.583
+// deleted the file as well as the export (`tests/unit/mockInfrastructureRetired.test.js`).
 module.exports = {
-  get MockMQClient() { return MockMQClient; },
-  get MockRegistry() { return MockRegistry; },
-  get MockStorage() { return MockStorage; },
-
   get CookbookTestUtils() { return CookbookTestUtils; },
   get ServiceReadinessValidator() { return ServiceReadinessValidator; },
   get CookbookTestRunner() { return CookbookTestRunner; },
@@ -82,11 +83,18 @@ module.exports = {
   get parseHandlerRef() { return require('./utils/handlerRef').parseHandlerRef; },
   get resolveHandlerModule() { return require('./utils/handlerRef').resolveHandlerModule; },
 
+  // The other half of what a service's integration harness needs to build its
+  // throwaway schema: which .sql files make up the set, and in which order.
+  // `createThrowawaySchema` above resolves the plan itself; a harness that
+  // builds its own schema step by step reads the plan directly, and had to
+  // reach into `src/utils/setupDatabase` to get it — a path inside the package
+  // is not a contract, and every move of `src/utils/` would break a consumer
+  // that never agreed to one. Exported as the identical function, not a
+  // wrapper: one definition, one behaviour (`change-discipline.md` § One rail
+  // per concern).
+  get resolveMigrationPlan() { return require('./utils/setupDatabase').resolveMigrationPlan; },
+
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get BizCiGateContract() { return BizCiGateContract; },
-  get IntegrationRun() { return require('./utils/integrationRun'); },
-
-  createMockMQ: () => new MockMQClient(),
-  createMockRegistry: () => new MockRegistry(),
-  createMockStorage: () => new MockStorage()
+  get IntegrationRun() { return require('./utils/integrationRun'); }
 };