@onlineapps/conn-orch-validator 9.0.0 → 10.0.0

package/src/utils/stepFailure.js

@@ -15,7 +15,27 @@
  * `result.validationErrors` / `result.error` and was discarded at both ends,
  * so a failed biz-hello boot could not be diagnosed from its own logs
  * (automation-gates.md §5 — silence is a defect).
+ *
+ * `results.steps` holds TWO kinds of record and they are not both steps. A step
+ * result is one; the entry `CookbookTestRunner.runCookbooks` pushes for a file
+ * the format check rejected is the other — a whole cookbook that produced no
+ * step at all. Each says which it is in `kind`, written where the record is
+ * made, so nothing here infers it from a missing field
+ * (`.claude/rules/architecture-principles.md` §8, Explicit Over Implicit).
+ * Until d.516b the two were conflated, and a rejected file was reported as
+ * `cookbook "broken.json" step "step #1": …` — a step that does not exist, in
+ * the one line whose job is to find the case.
+ */
+
+/** A record that IS a cookbook step: a `step_id` names it, and one must. */
+const KIND_STEP = 'step';
+
+/**
+ * A record standing for a whole cookbook that never produced a step — the file
+ * could not be loaded, or the format check rejected it. It carries no
+ * `step_id`, because it is no step.
  */
+const KIND_COOKBOOK_LOAD_FAILURE = 'cookbook-load-failure';
 
 /**
  * Which step this is — for a log line, an error list, anything a human reads.
@@ -26,29 +46,51 @@
  * every conforming cookbook logged `Step undefined: FAILED …` — measured in the
  * live biz-converter log on 2026-08-29 against a cookbook that is correct.
  *
- * The position is the last resort and it is a real answer: `step #3 (operation:
- * convert)` finds the step in the file, which `undefined` never did. A reader
- * who cannot tell which step failed has the same problem as one who was told
- * nothing (automation-gates.md §5).
+ * **A step without `step_id` is a defect, not a step to be labelled some other
+ * way.** Until d.516b this fell back to the position, `step #3 (operation:
+ * convert)`, which was the right answer while the shape was still settling: the
+ * alternative on the day was `undefined`. It is the wrong answer now. Since
+ * `@onlineapps/cookbook-core` 5.0.0 the schema requires `step_id` on every task
+ * step (`schemas/cookbook.v2.schema.json` definitions.TaskStep.required lists
+ * step_id, type, service, operation), `readCookbookSteps` refuses a step
+ * spelling it `id`, `CookbookTestRunner.validateCookbook` refuses a cookbook
+ * whose step omits it, and the orchestrator will not run a task step that fails
+ * to name its operation either (`@onlineapps/conn-orch-orchestrator`
+ * § _requireStepOperation, d.460). So the only step that can still arrive here
+ * without one is a broken step, and inventing a name for it is the silent
+ * substitution `.claude/rules/architecture-principles.md` §3 forbids — it makes
+ * the diagnostics read as if the cookbook were fine.
+ *
+ * This is about STEPS. A cookbook that produced none is a different record and
+ * is never handed to this function (`describeStepFailureWithContext` below).
+ *
+ * The position is still in the message, because it is what finds the offending
+ * step in the file; it is now part of saying WHAT IS WRONG rather than a name
+ * standing in for one (§5, `[Context] Problem - Expected/Fix`).
  *
  * @param {Object} step - a cookbook step, or a step result carrying the same keys
  * @param {number} index - zero-based position within the cookbook
- * @returns {string} never empty, never "undefined"
+ * @returns {string} the step's own `step_id`; never empty, never "undefined"
+ * @throws {Error} when the step names no `step_id`
  */
 function describeStepIdentity(step, index) {
   if (!step || typeof step !== 'object') {
     throw new Error('[stepFailure] step is required - Expected the cookbook step (or its result) to name in a message');
   }
 
-  // `step_id` only. `normalizeCookbookSteps` refuses a step spelling it `id`,
-  // so a step reaching here can no longer carry the retired name.
+  // `step_id` only. `readCookbookSteps` refuses a step spelling it `id`, so a
+  // step reaching here can no longer carry the retired name.
   if (typeof step.step_id === 'string' && step.step_id.length > 0) return step.step_id;
 
   const position = Number.isInteger(index) && index >= 0 ? index + 1 : 1;
   const operation = typeof step.operation === 'string' && step.operation.length > 0
     ? ` (operation: ${step.operation})`
     : '';
-  return `step #${position}${operation}`;
+  throw new Error(`[stepFailure] Step #${position}${operation} has no step_id - every step of a v2.1 `
+    + 'cookbook is addressed by its own step_id, so there is no name to report this step under '
+    + '(@onlineapps/cookbook-core schemas/cookbook.v2.schema.json definitions.TaskStep.required). '
+    + `Fix: add "step_id" to step #${position} of the cookbook `
+    + '(api/docs/biz/40-cookbooks/format.md § Required fields).');
 }
 
 /**
@@ -89,21 +131,66 @@ function describeStepFailure(stepResult) {
 }
 
 /**
- * The same reason, prefixed with enough context to find the case: which
- * cookbook, which step, which operation. This is what step 4 puts into
- * `results.errors`.
+ * How a failed record is NAMED, by what it is.
+ *
+ * `results.steps` carries two kinds and only one of them is a step (d.516b), so
+ * the name of a record is a decision about its `kind` — and one decision has one
+ * owner. Until d.523 it was made here for the orchestrator's error list and
+ * again, differently, in `utils/preValidation.js` for the CLI's, where the
+ * second copy did not make it at all: `src/cli/biz-ci-gate.js` printed
+ * `step_id` for both kinds, so a rejected cookbook reached the operator as
+ * `undefined` — the very shape d.516b removed from the other channel
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {Object} record a step result, or a cookbook-load failure
+ * @returns {string} `cookbook "<file>"` or `step "<step_id>"`
+ */
+function describeRecordIdentity(record) {
+  if (!record || typeof record !== 'object') {
+    throw new Error('[stepFailure] record is required - Expected a failed entry of results.steps to name '
+      + 'in a message. Fix: pass the record, not its reason.');
+  }
+
+  if (record.kind === KIND_COOKBOOK_LOAD_FAILURE) {
+    return `cookbook "${record.cookbook || 'unknown cookbook'}"`;
+  }
+
+  return `step "${describeStepIdentity(record, record.stepIndex)}"`;
+}
+
+/**
+ * The same reason, prefixed with enough context to find the case. WHICH context
+ * depends on what the record is, and the record says so in `kind`:
  *
- * @param {Object} stepResult - a step result carrying `cookbook`
+ *   - a cookbook that never produced a step is named by the FILE and nothing
+ *     else. There is no step in it, so there is no step to name;
+ *   - a step failure is named by cookbook, step and operation, as before.
+ *
+ * This is what step 4 puts into `results.errors`.
+ *
+ * @param {Object} record - a step result, or a cookbook-load failure, carrying
+ *   `cookbook` and its own `kind`
  * @returns {string}
  */
-function describeStepFailureWithContext(stepResult) {
-  const reason = describeStepFailure(stepResult);
-  const cookbook = stepResult.cookbook || 'unknown cookbook';
+function describeStepFailureWithContext(record) {
+  const reason = describeStepFailure(record);
+  const cookbook = record.cookbook || 'unknown cookbook';
+
+  if (record.kind === KIND_COOKBOOK_LOAD_FAILURE) {
+    return `${describeRecordIdentity(record)} could not be run: ${reason}`;
+  }
+
   // One owner for "which step": `unnamed step` used to be the answer for every
   // conforming cookbook, because the result carried neither identifier.
-  const stepId = describeStepIdentity(stepResult, stepResult.stepIndex);
-  const operation = stepResult.operation ? ` (${stepResult.operation})` : '';
-  return `cookbook "${cookbook}" step "${stepId}"${operation}: ${reason}`;
+  const operation = record.operation ? ` (${record.operation})` : '';
+  return `cookbook "${cookbook}" ${describeRecordIdentity(record)}${operation}: ${reason}`;
 }
 
-module.exports = { describeStepIdentity, describeStepFailure, describeStepFailureWithContext };
+module.exports = {
+  describeStepIdentity,
+  describeRecordIdentity,
+  describeStepFailure,
+  describeStepFailureWithContext,
+  KIND_STEP,
+  KIND_COOKBOOK_LOAD_FAILURE
+};

package/src/utils/testCoverageContract.js

@@ -43,6 +43,23 @@
  * why the jest binary is the SERVICE's own (resolved from its `node_modules`),
  * not this package's: a different jest version resolves a different `testMatch`.
  *
+ * ## Why an empty set is a finding rather than a clean run
+ *
+ * Every comparison here iterates a set, so over an empty one it finds no
+ * counter-example — and an empty match is jest's own exit 0 with no output.
+ * A repository whose jest matched nothing therefore passed, and the gate printed
+ * `0 file(s) matched, 0 run by the test:all chain` as if that were a
+ * measurement. The same held one level down: a `test:all` step aimed at an empty
+ * directory listed 0 files, exited 0, and contributed nothing to either side of
+ * any comparison (both measured 2026-09-15, finding d.205).
+ *
+ * So an empty T, and an empty answer from any jest invocation the chain reaches,
+ * are named: a gate that reports OK over something it never observed is the
+ * false guarantee automation-gates.md §5 calls a defect of the same severity as
+ * a wrong result. Each is reported only where it is the ROOT — an empty T
+ * silences the per-step check, and so does a file on disk that the config does
+ * not match, because there every empty step is that defect's shadow.
+ *
  * ## Why a declared tier exists at all
  *
  * `tests/e2e/mq-invocation` needs a live consumer on the service workflow queue.
@@ -77,7 +94,8 @@ const { spawnSync } = require('child_process');
 
 const TEST_COVERAGE_SCOPE = 'files the service jest config matches (jest --listTests) vs. the files '
   + 'the test:all chain runs, decomposed npm run → jest, plus the scripts declared in contract stackTiers; '
-  + 'and that same matched set vs. every platform test file present on disk (**/tests/**/*.test.js)';
+  + 'and that same matched set vs. every platform test file present on disk (**/tests/**/*.test.js); '
+  + 'and that neither the matched set nor any jest invocation the test:all chain reaches is empty';
 
 const TEST_COVERAGE_NOT_MEASURED = 'whether a declared stack tier is ever RUN — the declaration says '
   + 'why it cannot run in test:all, never that something else runs it';
@@ -437,10 +455,31 @@ function verifyTestCoverage({ serviceRoot, contract, spawn = spawnSync }) {
   const relative = (absolutePath) => path.relative(serviceRoot, absolutePath);
   const violations = [];
   const add = (requirement, message) => violations.push({ requirement, message });
+  const has = (requirement) => violations.some((violation) => violation.requirement === requirement);
 
   // T — everything the service's jest config matches, asked without a path filter.
   const matched = new Set(ask([]));
 
+  // T = ∅ — the gate ran and measured nothing.
+  //
+  // An empty match is jest's own exit 0 with no output (§ listTests), so nothing
+  // in the run distinguishes it from a healthy one. And every comparison below
+  // iterates a set: over an empty T, T \ (A ∪ B) and D \ T find no
+  // counter-example for the same reason an empty sum is zero. The gate printed
+  // "OK test-coverage — 0 file(s) matched, 0 run by the test:all chain" and the
+  // reader took it for a measurement (measured 2026-09-15, finding d.205).
+  //
+  // Reported here and nowhere else: when the config matches nothing, every step
+  // of the chain lists nothing too, and one defect with one fix must not arrive
+  // as one violation per step.
+  if (matched.size === 0) {
+    add('TEST_SET_EMPTY', 'Nothing measured - the service jest config matches 0 test files, '
+      + 'so "jest --listTests" (the service\'s own jest, no path filter) returns an empty set, every '
+      + 'comparison this gate makes is vacuously satisfied, and the run prints OK over a service whose '
+      + `coverage was never observed. Fix: widen testMatch in jest.config.js to the platform pattern `
+      + `(${PLATFORM_TEST_FILE_PATTERN}), or add the test files the service is missing.`);
+  }
+
   // D \ T — a suite that is on disk and in no jest answer. Checked FIRST because
   // it is the only defect the other three cannot express: a file jest does not
   // match is missing from both sides of every comparison below, so silence there
@@ -459,7 +498,26 @@ function verifyTestCoverage({ serviceRoot, contract, spawn = spawnSync }) {
   for (const problem of chain.problems) add('TEST_ALL_CHAIN', problem.message);
   const inTestAll = new Set();
   for (const command of chain.commands) {
-    for (const file of ask(command.args)) inTestAll.add(file);
+    const files = ask(command.args);
+
+    // A step that lists nothing runs nothing — and says so with exit 0, so the
+    // script stays green in every pipeline while measuring nothing. It is what a
+    // narrowed pattern, a renamed directory or a moved suite leaves behind, and
+    // it is invisible to every other check here: a step contributing no file
+    // changes neither side of any comparison.
+    // Only where the matched set is the whole truth: T non-empty (checked above)
+    // and nothing on disk left outside it. A config that misses files on disk is
+    // already named, and every step aimed at those files lists 0 as a CONSEQUENCE
+    // of it — reporting the shadow beside the thing casting it buries the fix.
+    if (matched.size > 0 && !has('TEST_NOT_MATCHED') && files.length === 0) {
+      const invocation = ['jest', ...command.args].join(' ').trim();
+      add('TEST_SET_EMPTY', `Chain step runs no test - "${CHAIN_ENTRY_SCRIPT}" reaches `
+        + `"${invocation}" (via ${command.viaScript}), and jest lists 0 files for it, so the step exits 0 `
+        + `having measured nothing. Fix: point "${command.viaScript}" at the tests it is meant to run, `
+        + `or remove the step from the ${CHAIN_ENTRY_SCRIPT} chain.`);
+    }
+
+    for (const file of files) inTestAll.add(file);
   }
 
   // B — everything the declared stack tiers run.

package/src/utils/throwawaySchema.js

@@ -40,10 +40,21 @@
  *
  * THE SCHEMA IS CHOSEN BY THE CALLER, NEVER BY THE FILE. A migration written
  * for the install runner commonly opens with `USE \`oagen_<service>\`;` — the
- * production schema by name. Applied verbatim against a throwaway, that one line
- * sends the whole file into the live schema instead. Those lines are therefore
- * stripped, and a schema select that survives the strip stops the build rather
- * than being applied.
+ * production schema by name (measured 2026-09-16: 69 live migrations, in
+ * api_biz/meta and api_biz/property). Applied verbatim against a throwaway, that
+ * one line sends the whole file into the live schema instead. Those lines are
+ * therefore stripped, and a schema select that survives the strip stops the
+ * build rather than being applied.
+ *
+ * Stripping is only half of it, because it moves the statements that carry no
+ * schema of their own. A name qualified with a schema — `INSERT INTO
+ * \`oagen_meta\`.persons …` — goes where it says whatever the runner selected,
+ * so it is refused outright rather than stripped: the rule is "the throwaway, or
+ * nothing", and the single exception is `information_schema`, which is read-only
+ * and whose `DATABASE()` follows the connection. Refusing is right even for a
+ * name that a strip could rewrite: what a test rewrites, it also has to be
+ * trusted to rewrite correctly, and a shim over somebody else's SQL is the
+ * workaround `change-discipline.md` forbids.
  *
  * @see src/utils/setupDatabase.js — the CI build, and the shared decisions
  * @see src/utils/deployContract.js — R8, which permits a file that imports this
@@ -66,6 +77,37 @@ const LEADING_SCHEMA_SELECT = /^\s*USE\s+/i;
 const SURVIVING_SCHEMA_SELECT = /(?:^|;)\s*USE\s+/i;
 /** An SQL comment line — prose cannot select a schema. */
 const SQL_COMMENT = /^\s*(?:--|#|\/\*|\*)/;
+/** Everything a `--` or `#` opens on a line is prose too, wherever it starts. */
+const TRAILING_COMMENT = /(--|#).*$/;
+
+/**
+ * The positions where `a.b` is `<schema>.<object>` and not `<alias>.<column>`:
+ * a name in the TARGET position of a statement. Aliases live in expressions —
+ * after `ON`, after `SET`, in a `WHERE`, in the select list — and never
+ * directly after one of these keywords. That is why the check anchors on the
+ * keyword instead of matching every dotted token: measured over the live SQL of
+ * `api_biz/*` (2026-09-16), adding `ON` to the list turned 19 column references
+ * into findings, and matching dotted tokens outright would turn every alias in
+ * the tree into one.
+ */
+const QUALIFIED_TARGET = new RegExp(
+  '\\b(?:FROM|JOIN|INTO|UPDATE|TABLE|REFERENCES|TRUNCATE|VIEW|TRIGGER|PROCEDURE|FUNCTION|CALL)\\s+'
+  + '(?:IF\\s+(?:NOT\\s+)?EXISTS\\s+)?'
+  + '`?([A-Za-z0-9_$]+)`?\\s*\\.\\s*`?[A-Za-z0-9_$]+`?',
+  'gi'
+);
+
+/**
+ * The one qualifier a file may name besides the throwaway: the server's own
+ * catalog. It is read-only — the server refuses a write to it — and reading it
+ * is how a portable migration asks about its own shape
+ * (`SELECT … FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE()`,
+ * where `DATABASE()` is the schema the runner selected, i.e. the throwaway).
+ * Measured 2026-09-16: 22 live migration files in converter, ingest, meta and
+ * property read it that way, and every one of them is correct — a refusal there
+ * would be a finding nobody could fix (`automation-gates.md` §3).
+ */
+const CATALOG_SCHEMA = 'information_schema';
 
 function require_(value, name, fix) {
   if (value === undefined || value === null || value === '') {
@@ -74,13 +116,44 @@ function require_(value, name, fix) {
   return value;
 }
 
+/**
+ * The schemas a file names in a statement's target position, other than the one
+ * the runner selected. Comments are prose and are removed first, both the lines
+ * that are wholly comment and the tail a `--` opens on a line of SQL.
+ *
+ * @param {string} sql the SQL being applied
+ * @param {string} schema the throwaway the runner selected
+ * @returns {string[]} distinct qualifiers, in the order they appear
+ */
+function foreignQualifiers(sql, schema) {
+  const found = [];
+
+  for (const line of sql.split('\n')) {
+    if (SQL_COMMENT.test(line)) continue;
+    const code = line.replace(TRAILING_COMMENT, '');
+
+    for (const match of code.matchAll(QUALIFIED_TARGET)) {
+      const qualifier = match[1];
+      if (qualifier === schema) continue;
+      if (qualifier.toLowerCase() === CATALOG_SCHEMA) continue;
+      if (!found.includes(qualifier)) found.push(qualifier);
+    }
+  }
+
+  return found;
+}
+
 /**
  * The SQL of one migration, with the install runner's schema select removed.
  *
  * @param {string} file absolute path to the .sql file
+ * @param {string} schema the throwaway schema the statements are applied to
  * @returns {string}
  */
-function sqlWithoutSchemaSelect(file) {
+function sqlWithoutSchemaSelect(file, schema) {
+  require_(schema, 'schema', 'pass the throwaway schema the statements are applied to; '
+    + 'without it there is nothing to compare a qualified name against.');
+
   const stripped = fs.readFileSync(file, 'utf8')
     .split('\n')
     .map((line) => (LEADING_SCHEMA_SELECT.test(line) ? '' : line))
@@ -99,6 +172,18 @@ function sqlWithoutSchemaSelect(file) {
       + 'schema for the file.');
   }
 
+  const foreign = foreignQualifiers(stripped, schema);
+  if (foreign.length > 0) {
+    throw new Error(`[ThrowawaySchema] ${path.basename(file)} names the schema `
+      + `"${foreign.join('", "')}" in a statement, and the throwaway is "${schema}" - refusing to `
+      + 'apply it.\n'
+      + '       Stripping the USE lines only moves the statements that carry no schema of their own; '
+      + 'a qualified name sends its statement somewhere else whatever the runner selected, and in a '
+      + 'migration that somewhere is the live schema.\n'
+      + '       Fix: write the name unqualified - the runner selects the schema for the file. '
+      + `Only ${CATALOG_SCHEMA} may be named, because it is read-only and follows DATABASE().`);
+  }
+
   return stripped;
 }
 
@@ -171,7 +256,7 @@ async function createThrowawaySchema({
 
   const apply = async (file, kind) => {
     const result = await exec({
-      connection: conn, schema, file, sql: sqlWithoutSchemaSelect(file)
+      connection: conn, schema, file, sql: sqlWithoutSchemaSelect(file, schema)
     });
     if (result.status !== 0) {
       throw new Error(`[ThrowawaySchema] ${kind} ${path.basename(file)} failed:\n${result.stderr}\n`
@@ -198,7 +283,7 @@ async function createThrowawaySchema({
     migrationsApplied: toApply.length,
     seedsApplied: seedFiles.length,
     migrations: [...plan.migrations],
-    readMigration: (name) => sqlWithoutSchemaSelect(fileOf(name)),
+    readMigration: (name) => sqlWithoutSchemaSelect(fileOf(name), schema),
     applyMigration: async (name) => apply(fileOf(name), 'Migration'),
     dispose: async () => run(dropSql)
   };

package/src/validatorIdentity.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Who this validator IS — its own name and its own version.
+ *
+ * A validation proof and a deployability signal both NAME their author, and
+ * that name is not a caller's to choose: it is this package's identity, and the
+ * one place it is written down is this package's `package.json`. Read once,
+ * here, so the value cannot differ between the documents that carry it.
+ *
+ * Before this the same fact stood in four places: twice as
+ * `require('../package.json').version` inside `ValidationOrchestrator`, once
+ * more in `utils/preValidation.js` beside a hand-written copy of the package
+ * NAME, and once in `validators/ValidationProofGenerator` as
+ * `options.validatorVersion || '1.0.0'` — an invented number that reached a
+ * signed document whenever the caller passed none
+ * (`.claude/rules/architecture-principles.md` §3, No Fallbacks).
+ *
+ * This is the package's own metadata, not configuration: nothing about it is
+ * environment- or caller-dependent, so there is nothing to inject.
+ */
+
+const { name, version } = require('../package.json');
+
+/** `@onlineapps/conn-orch-validator` — the author every proof names. */
+const VALIDATOR_NAME = name;
+
+/** The published version of this package, as its manifest states it. */
+const VALIDATOR_VERSION = version;
+
+module.exports = { VALIDATOR_NAME, VALIDATOR_VERSION };

package/src/validators/ServiceStructureValidator.js

@@ -460,10 +460,15 @@ class ServiceStructureValidator {
       this.info.push('✓ Found Configuration directory');
     }
 
+    // `tests/cookbooks` is NOT here: it is a boot condition, raised by
+    // `validateTestStructure()` as an error (d.584). These two are
+    // recommendations — no row of the biz-service uniform demands that either
+    // directory exist (`S-TEST` fixes the body of `npm test`, `S-INT-C` carries
+    // `only_with: tests/integration`), so this is the only thing that mentions
+    // them and it stays a warning.
     const recommendedDirs = [
       { path: 'tests/unit', description: 'Unit tests' },
-      { path: 'tests/integration', description: 'Integration tests' },
-      { path: 'tests/cookbooks', description: 'Cookbook tests' }
+      { path: 'tests/integration', description: 'Integration tests' }
     ];
 
     for (const dir of requiredDirs) {
@@ -871,23 +876,44 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate test structure
+   * Validate test structure — `tests/cookbooks` with at least one recipe.
+   *
+   * This is a BOOT CONDITION, not a recommendation (d.584): Tier-1 validates
+   * the service's operations BY these recipes at phase 0.2, so a service
+   * without them does not start. Until d.584 the absence was reported twice
+   * and softly — a `MISSING_RECOMMENDED_DIRECTORY` warning when the directory
+   * was gone, a `NO_COOKBOOK_TESTS` warning when it was empty — and the run
+   * then died four steps later on the proof, which `ValidationProofGenerator`
+   * refuses for `testsRun: 0` under the unrelated name NO_TESTS. Late,
+   * indirect, and in two voices; now one error, at the step that checks it
+   * (`automation-gates.md` §1 requirement 4).
+   *
+   * The same fact is already stated from the other side by rule
+   * F-DOCKERIGNORE, which excludes the whole test tree from the production
+   * image and keeps `tests/cookbooks` (d.560). One rail, two readers.
+   *
+   * What counts as a recipe is what the runner counts —
+   * `CookbookTestRunner.runCookbooks` reads the `.json` files of this
+   * directory — so the two never disagree about an empty set.
    */
   validateTestStructure() {
     const cookbooksPath = path.join(this.serviceRoot, 'tests/cookbooks');
-    if (fs.existsSync(cookbooksPath)) {
-      const cookbookFiles = fs.readdirSync(cookbooksPath).filter(f => f.endsWith('.json'));
-      if (cookbookFiles.length === 0) {
-        this.warnings.push({
-          type: 'NO_COOKBOOK_TESTS',
-          path: 'tests/cookbooks',
-          message: 'No cookbook tests found in tests/cookbooks/',
-          fix: 'Create cookbook tests for pre-validation. See: /docs/standards/TESTING.md'
-        });
-      } else {
-        this.info.push(`✓ Found ${cookbookFiles.length} cookbook test(s)`);
-      }
+    const cookbookFiles = fs.existsSync(cookbooksPath)
+      ? fs.readdirSync(cookbooksPath).filter(f => f.endsWith('.json'))
+      : [];
+
+    if (cookbookFiles.length === 0) {
+      this.errors.push({
+        type: 'MISSING_COOKBOOKS',
+        path: 'tests/cookbooks',
+        message: '[ServiceStructure] tests/cookbooks is missing or empty - Tier-1 boot '
+          + 'validates operations by these recipes. Fix: add tests/cookbooks/<op>.json',
+        fix: 'add tests/cookbooks/<op>.json'
+      });
+      return;
     }
+
+    this.info.push(`✓ Found ${cookbookFiles.length} cookbook test(s)`);
   }
 
   /**

package/src/validators/ValidationProofGenerator.js

@@ -1,6 +1,30 @@
 'use strict';
 
 const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
+const { VALIDATOR_NAME, VALIDATOR_VERSION } = require('../validatorIdentity');
+
+/**
+ * Read one measurement out of the runner's aggregate, or refuse.
+ *
+ * Every number in a validation proof is a measurement of a run that happened,
+ * so a missing one has no substitute value. The four fields below used to be
+ * filled with `testResults.<field> || 0`, which turned "nobody measured this"
+ * into "measured, and it was zero" — the same number, and no way for a reader
+ * of the proof to tell which of the two it is (`architecture-principles.md` §3,
+ * No Fallbacks).
+ */
+function readMeasurement(testResults, field, proofField) {
+  const value = testResults === null || testResults === undefined ? undefined : testResults[field];
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    const rendered = typeof value === 'number' ? String(value) : JSON.stringify(value);
+    throw new Error(`[ValidationProofGenerator] Missing measurement - testResults.${field} is ${rendered}, `
+      + `and the proof field ${proofField} may not be filled from anything else. `
+      + 'Fix: hand in the aggregate CookbookTestRunner.runCookbooks() returns, which counts every step it ran.');
+  }
+
+  return value;
+}
 
 /**
  * ValidationProofGenerator - Generates validation proof from test results
@@ -15,10 +39,25 @@ const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
  */
 class ValidationProofGenerator {
   constructor(options = {}) {
+    // WHO the validator is is not an option. It used to be one, with
+    // `|| '1.0.0'` behind it, so a caller that passed nothing got an invented
+    // version inside a signed document — and a caller that passed something got
+    // to say this package was whatever it liked. The identity has one owner
+    // (`src/validatorIdentity.js`), and an attempt to set it is refused rather
+    // than ignored: an option that silently does nothing is the implicit
+    // behaviour `.claude/rules/architecture-principles.md` §8 forbids.
+    for (const retired of ['validatorName', 'validatorVersion']) {
+      if (options[retired] !== undefined) {
+        throw new Error(`[ValidationProofGenerator] ${retired} is not an option - the proof names THIS `
+          + `package (${VALIDATOR_NAME} ${VALIDATOR_VERSION}), read from its own package.json. `
+          + `Fix: drop ${retired} from the constructor options.`);
+      }
+    }
+
     this.serviceName = options.serviceName;
     this.serviceVersion = options.serviceVersion;
-    this.validatorName = options.validatorName || '@onlineapps/conn-orch-validator';
-    this.validatorVersion = options.validatorVersion || '1.0.0';
+    this.validatorName = VALIDATOR_NAME;
+    this.validatorVersion = VALIDATOR_VERSION;
   }
 
   /**
@@ -26,9 +65,14 @@ class ValidationProofGenerator {
    *
    * @param {Object} testResults - Results from test execution
    * @param {Object} dependencies - Service dependencies with versions
+   * @param {Object} [options] - what the caller MEASURED about the service
+   * @param {string} [options.contractFingerprint] - the fingerprint of the
+   *   contract this run validated, when the caller computed one. Absent means
+   *   absent: the field is left out rather than filled with a placeholder, and
+   *   the proof schema marks it optional for exactly that reason.
    * @returns {Object} Validation proof with metadata
    */
-  generateProof(testResults, dependencies = {}) {
+  generateProof(testResults, dependencies = {}, { contractFingerprint } = {}) {
     // Transform test results to ValidationProofSchema format
     const validationData = {
       serviceName: this.serviceName,
@@ -36,44 +80,39 @@ class ValidationProofGenerator {
       validator: this.validatorName,
       validatorVersion: this.validatorVersion,
       validatedAt: new Date().toISOString(),
-      durationMs: testResults.duration || 0,
-      testsRun: testResults.total || 0,
-      testsPassed: testResults.passed || 0,
-      testsFailed: testResults.failed || 0,
+      durationMs: readMeasurement(testResults, 'duration', 'durationMs'),
+      testsRun: readMeasurement(testResults, 'total', 'testsRun'),
+      testsPassed: readMeasurement(testResults, 'passed', 'testsPassed'),
+      testsFailed: readMeasurement(testResults, 'failed', 'testsFailed'),
       dependencies: dependencies || {}
     };
 
+    if (contractFingerprint !== undefined) {
+      validationData.contractFingerprint = contractFingerprint;
+    }
+
+    // A run that executed nothing has nothing to certify. `runPreValidation`
+    // writes a proof whenever no step FAILED, and a service whose
+    // tests/cookbooks/ holds no .json file has no failing step — so this
+    // generator used to author a signed proof claiming a passing validation of
+    // zero tests, and the CLI printed `OK run-prevalidation` beside it.
+    //
+    // The platform already held that such a proof is invalid: the same codec's
+    // decode() refuses `testsRun <= 0` as NO_TESTS. Only the party AUTHORING it
+    // did not, so the contradiction surfaced at the registry, days later and far
+    // from the cause. It is refused here, where it is created
+    // (`architecture-principles.md` §4, Fail-Fast).
+    if (validationData.testsRun === 0) {
+      throw new Error('[ValidationProofGenerator] Refusing a proof for a run that executed nothing - '
+        + 'testsRun is 0, so the proof would claim a passing validation of cookbooks that never ran; '
+        + 'ValidationProofCodec.decode() refuses exactly this proof as NO_TESTS. '
+        + 'Fix: give the service the cookbooks its operations are validated by, under tests/cookbooks/.');
+    }
+
     // Delegate encoding to centralized codec
     // This ensures Generator and Verifier use EXACTLY the same algorithm
     return ValidationProofCodec.encode(validationData);
   }
-
-  /**
-   * Extract test results summary
-   */
-  extractTestSummary(testResults) {
-    return {
-      total: testResults.total || 0,
-      passed: testResults.passed || 0,
-      failed: testResults.failed || 0,
-      duration: testResults.duration || 0,
-      coverage: testResults.coverage || 0
-    };
-  }
-
-  /**
-   * Create validation error
-   */
-  createValidationError(code, message, details = {}) {
-    return {
-      error: {
-        code,
-        message,
-        details,
-        timestamp: new Date().toISOString()
-      }
-    };
-  }
 }
 
 module.exports = ValidationProofGenerator;