@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

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,50 @@ 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',
+        // The problem only. The remedy is `fix`, and the printer composes the
+        // two — `formatResult` below writes a `Fix:` line of its own, the
+        // service wrapper composes `message (Fix: fix)` inline. A message that
+        // carries `Fix:` as well prints the remedy twice, which reads as two
+        // instructions; this was the only one of the validator's findings that
+        // did it (d.599).
+        message: '[ServiceStructure] tests/cookbooks is missing or empty - Tier-1 boot '
+          + 'validates operations by these recipes.',
+        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;

package/templates/business-service/.dockerignore

@@ -1,7 +1,12 @@
 # --- oa-dockerignore v1
 # Derived from templates/business-service/gitignore, the declaration .gitignore reads too —
 # what a LOCAL production build must not copy into the image (being ignored by git
-# excludes nothing from COPY . .). Everything above this block is this repository's own.
+# excludes nothing from COPY . .), PLUS the test tree: tests stay in the repository
+# and out of the artefact that runs, the same decision the library uniform makes as
+# L-PACK-TESTS. The one exception is tests/cookbooks, which is not a test but a
+# declaration the runtime reads — Tier-1 of the boot runs those cookbooks at phase
+# 0.2, and an image without them refuses its own validation proof as NO_TESTS.
+# Everything above this block is this repository's own.
 node_modules
 **/node_modules
 config/runtime
@@ -38,5 +43,8 @@ Thumbs.db
 **/Thumbs.db
 .oa_drive_deps_hash
 **/.oa_drive_deps_hash
+tests
+**/tests
+!tests/cookbooks
 .git
 # --- end oa-dockerignore v1