@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/utils/preValidation.js

@@ -74,15 +74,23 @@ function assertV3Operations(serviceRoot) {
 }
 
 /**
+ * A run narrowed by `operationFilter` writes NO proof, and that is the whole
+ * reason the flag can exist. A validation proof is the claim that the service's
+ * cookbooks passed; a run of some of them cannot make that claim, and a proof
+ * written from one would let the registry trust a run that never happened —
+ * the same reason a FAILED run writes none.
+ *
  * @param {object} params
  * @param {string} params.serviceRoot service repository root
- * @param {string} params.serviceUrl resolved by the caller from the service's own config
  * @param {Function} params.RunnerClass CookbookTestRunner (injected so the module stays testable)
  * @param {Function} params.ProofGeneratorClass ValidationProofGenerator
  * @param {{log: Function, error: Function}} params.logger
- * @returns {Promise<{ok: boolean, results: object, failedSteps: Array, proof: object|null, proofPath: string|null}>}
+ * @param {string} [params.operationFilter] JavaScript regular expression; only the
+ *        cookbooks running a matching operation are executed
+ * @returns {Promise<{ok: boolean, results: object, failedSteps: Array, proof: object|null,
+ *          proofPath: string|null, filteredBy: string|null}>}
  */
-async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGeneratorClass, logger }) {
+async function runPreValidation({ serviceRoot, RunnerClass, ProofGeneratorClass, logger, operationFilter }) {
   const cookbooksDir = path.join(serviceRoot, COOKBOOKS_RELATIVE_DIR);
   if (!fs.existsSync(cookbooksDir)) {
     throw new Error(`[PreValidation] Missing cookbooks directory - ${cookbooksDir} is required. `
@@ -95,14 +103,15 @@ async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGen
 
   const runner = new RunnerClass({
     serviceName: packageJson.name,
-    serviceUrl,
     servicePath: serviceRoot,
     mockInfrastructure: true,
     timeout: COOKBOOK_TIMEOUT_MS,
     logger
   });
 
-  const results = await runner.runCookbooks(cookbooksDir);
+  const results = await runner.runCookbooks(cookbooksDir,
+    operationFilter === undefined ? {} : { operation: operationFilter });
+  const filteredBy = operationFilter === undefined ? null : operationFilter;
 
   if (results.failed > 0) {
     // No proof on a failed run. A proof is a claim that the cookbooks passed,
@@ -115,7 +124,11 @@ async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGen
         validationErrors: step.validationErrors || []
       }));
 
-    return { ok: false, results, failedSteps, proof: null, proofPath: null };
+    return { ok: false, results, failedSteps, proof: null, proofPath: null, filteredBy };
+  }
+
+  if (filteredBy !== null) {
+    return { ok: true, results, failedSteps: [], proof: null, proofPath: null, filteredBy };
   }
 
   const proofGenerator = new ProofGeneratorClass({
@@ -131,7 +144,7 @@ async function runPreValidation({ serviceRoot, serviceUrl, RunnerClass, ProofGen
   fs.mkdirSync(path.dirname(proofPath), { recursive: true });
   fs.writeFileSync(proofPath, JSON.stringify(proof, null, 2));
 
-  return { ok: true, results, failedSteps: [], proof, proofPath };
+  return { ok: true, results, failedSteps: [], proof, proofPath, filteredBy };
 }
 
 module.exports = { runPreValidation, PROOF_RELATIVE_PATH, COOKBOOKS_RELATIVE_DIR };

package/src/utils/setupDatabase.js

@@ -17,11 +17,13 @@
  *
  * Two invariants, both from ADR 0006:
  *
- *   §2 every .sql file in the declared directory is applied, in sorted order.
- *      No list lives in this file — the set grows with each schema change, and a
- *      list would drift until a missing table surfaced in an unrelated test.
+ *   §2 every .sql file in the declared directory is applied, in the order the
+ *      operator runner applies them (`migrationOrder.js` — `sort -V`, the one
+ *      definition of that order). No list lives in this file: the set grows with
+ *      each schema change, and a list would drift until a missing table
+ *      surfaced in an unrelated test.
  *
- *   §3 foreign key checks stay ON. Deferring them would let a migration
+ *   §3 the target is EMPTY and foreign key checks stay ON. Deferring them would let a migration
  *      reference a table a later file creates and still report success, which is
  *      the exact defect class building from empty exists to catch.
  *
@@ -35,6 +37,8 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+const { compareVersion } = require('./migrationOrder');
+
 function requireValue(value, name) {
   if (value === undefined || value === null || value === '') {
     throw new Error(`[SetupDatabase] Missing ${name} - Expected a value. `
@@ -63,7 +67,9 @@ function resolveMigrationPlan(serviceRoot, database) {
   const migrations = fs.readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
     .map((entry) => entry.name)
-    .sort()
+    // Version order, because that is what the operator runner uses to build the
+    // real installation — CI has to prove that artefact, not one of its own.
+    .sort(compareVersion)
     .map((name) => path.join(dir, name));
 
   if (migrations.length === 0) {
@@ -83,13 +89,26 @@ function resolveMigrationPlan(serviceRoot, database) {
   return { dir, migrations, seeds };
 }
 
-/** Run one statement or file through the CLI client. Injectable for tests. */
-function defaultExec({ connection, schema, sql, file }) {
+/**
+ * Run one statement or file through the CLI client. Injectable for tests.
+ *
+ * `capture: true` asks for the client's stdout as well, in the bare shape a
+ * caller can read — one value per line, no column names and no box drawing.
+ * Only the emptiness probe uses it; a migration produces no output to read.
+ */
+function defaultExec({ connection, schema, sql, file, capture = false }) {
   const client = ['mariadb', 'mysql'].find((bin) => !spawnSync(bin, ['--version'], { encoding: 'utf8' }).error);
   if (!client) {
     return {
       status: 1,
-      stderr: '[SetupDatabase] No mysql/mariadb client on PATH - required because migrations use DELIMITER. '
+      // The reason is unconditional, and it says so: every statement of this
+      // build goes through the CLI, the first CREATE DATABASE included, and
+      // there is no driver path here. It used to read "required because
+      // migrations use DELIMITER", which BIZ-hello met on 2026-09-14 with no
+      // DELIMITER anywhere in its migrations — a service without triggers read
+      // it as "this does not apply to me" (`architecture-principles.md` §5).
+      stderr: '[SetupDatabase] No mysql/mariadb client on PATH - every statement of this build runs through '
+        + 'the CLI, the first CREATE DATABASE included, and there is no driver path. '
         + 'Fix: install mariadb-client in the CI job image.'
     };
   }
@@ -99,6 +118,7 @@ function defaultExec({ connection, schema, sql, file }) {
   // MariaDB Connector/C 3.x requires TLS by default and the CI database is a
   // sidecar with none; the connection never leaves the job's private network.
   if (connection.requireTls !== true) args.push('--skip-ssl');
+  if (capture === true) args.push('--batch', '--skip-column-names');
   if (connection.password) args.push(`-p${connection.password}`);
   if (schema) args.push(schema);
 
@@ -109,11 +129,160 @@ function defaultExec({ connection, schema, sql, file }) {
 
   return {
     status: result.error ? 1 : result.status,
+    stdout: result.error ? '' : (result.stdout || ''),
     stderr: result.error ? result.error.message
       : (result.stderr || '').split('\n').filter((l) => !l.includes('Using a password')).join('\n').trim()
   };
 }
 
+/**
+ * Refuse a target that is not a throwaway.
+ *
+ * `database.schema` is the REAL name — `oagen_emailer`, the same string on the
+ * dev server and in production — so the name distinguishes nothing, and neither
+ * does "does the schema exist": every biz `.gitlab-ci.yml` has the sidecar
+ * create it empty through `MARIADB_DATABASE` before the job starts.
+ *
+ * What does distinguish them is the premise this whole build rests on: the
+ * migration set is proved by applying it to an EMPTY schema (ADR 0006 §3). A
+ * target that already holds tables breaks that premise twice over — the run
+ * proves nothing, because the tables it would create are already there, and it
+ * writes into somebody's data, because a declared seed carries no
+ * `IF NOT EXISTS`. Both halves are the same answer: stop.
+ *
+ * Reported as UNCERTAIN by BIZ-emailer on 2026-09-04 — "we found nothing that
+ * blocks such a run outside CI" — and there was nothing.
+ */
+function assertTargetIsEmpty({ exec, connection, schema }) {
+  const probe = exec({
+    connection,
+    capture: true,
+    sql: `SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = '${schema}';`
+  });
+
+  if (probe.status !== 0) {
+    throw new Error(`[SetupDatabase] Could not ask ${connection.host}:${connection.port} what ${schema} holds:\n`
+      + `${probe.stderr}\n`
+      + '       Fix: the build refuses to touch a schema it cannot inspect — give this account SELECT on '
+      + 'information_schema, or point DB_HOST at the CI database.');
+  }
+
+  const count = Number.parseInt(String(probe.stdout ?? '').trim(), 10);
+  if (!Number.isFinite(count)) {
+    throw new Error(`[SetupDatabase] The table count for ${schema} came back unreadable: `
+      + `"${String(probe.stdout ?? '').trim()}"\n`
+      + '       Fix: the executor must return the client stdout for a capture call; without a count '
+      + 'this build cannot tell a throwaway schema from a live one.');
+  }
+
+  if (count > 0) {
+    throw new Error(`[SetupDatabase] Schema ${schema} on ${connection.host}:${connection.port} already holds `
+      + `${count} table(s) - refusing to build.\n`
+      + '       The migration set is proved by applying it to an EMPTY schema (ADR 0006 §3); against a '
+      + 'populated one it proves nothing, and a seed would write into whatever is already there.\n'
+      + '       Fix: point DB_HOST at the throwaway database of the CI job (the sidecar creates it empty), '
+      + `or drop ${schema} first if this really is a disposable instance. Never aim this at a dev or `
+      + 'production server.');
+  }
+}
+
+/**
+ * The collation the schema must carry, or a refusal.
+ *
+ * Owner decision 2026-09-14 (`db-collation-declaration` 001): the collation is
+ * the service's own declaration, `database.collation` in the integration
+ * contract, and the same key the production runbook reads. There is no default
+ * and no server fallback — a DB-owning service that declares none stops the
+ * build (`architecture-principles.md` §3).
+ *
+ * Whether the VALUE is a collation name is the contract validator's rule
+ * (`bizCiGateContract.js`, which every gate reads the contract through), and
+ * whether a repository DECLARED one is uniform row `D-DB-COLLATION`. What
+ * belongs here is neither of those: this function cannot build without the
+ * value, so it refuses at its own entry (§4), the way `DB_HOST` is refused.
+ *
+ * @param {{collation?: string}} database the contract declaration
+ * @returns {string}
+ */
+function requireCollation(database) {
+  const declared = database.collation;
+  if (typeof declared === 'string' && declared.trim() !== '') return declared.trim();
+
+  throw new Error('[SetupDatabase] Missing database.collation - the schema is created with the collation the '
+    + 'service declares, and there is no default.\n'
+    + '       Fix: add "collation" to the "database" block of config/service/integration-contract.json '
+    + '(e.g. "utf8mb4_bin" — the collation this service\'s tables already use); '
+    + 'api/docs/biz/70-contracts/database-contract.md §1 owns the key, '
+    + 'api/docs/governance/confirmations/db-collation-declaration.md 001 the decision.');
+}
+
+/**
+ * What the server says the schema was created with, or null when there is none.
+ *
+ * This probe is the reason `CREATE DATABASE IF NOT EXISTS` is not enough, and
+ * the reason is measured rather than assumed (BIZ-DOCS, 2026-09-14, throwaway
+ * `mariadb:10.5.29`): over an existing database, `IF NOT EXISTS … COLLATE`
+ * changes nothing and reports success. Six biz pipelines have the sidecar
+ * create the schema from `MARIADB_DATABASE` before the job starts, so in the
+ * environment this gate actually runs in the database is already there — with
+ * the image default `utf8mb4_general_ci`. Creating "if not exists" would
+ * therefore report a schema built to the declaration while the server holds
+ * another one, which is the false guarantee `automation-gates.md` §5 names.
+ *
+ * @returns {string|null}
+ */
+function existingCollation({ exec, connection, schema }) {
+  const probe = exec({
+    connection,
+    capture: true,
+    sql: 'SELECT DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA '
+      + `WHERE SCHEMA_NAME = '${schema}';`
+  });
+
+  if (probe.status !== 0) {
+    throw new Error(`[SetupDatabase] Could not ask ${connection.host}:${connection.port} what collation `
+      + `${schema} was created with:\n${probe.stderr}\n`
+      + '       Fix: the build refuses to create or reuse a schema whose collation it cannot read — give this '
+      + 'account SELECT on information_schema, or point DB_HOST at the CI database.');
+  }
+
+  const answer = String(probe.stdout ?? '').trim();
+  return answer === '' ? null : answer;
+}
+
+/**
+ * Create the schema with the declared collation, or refuse a schema that
+ * already carries another one.
+ *
+ * Never `IF NOT EXISTS`: see `existingCollation` above for what that silence
+ * costs.
+ */
+function createDatabaseSql(schema, collation) {
+  return `CREATE DATABASE \`${schema}\` COLLATE ${collation};`;
+}
+
+function createSchema({ exec, connection, schema, collation }) {
+  const present = existingCollation({ exec, connection, schema });
+
+  if (present === collation) return;
+
+  if (present !== null) {
+    throw new Error(`[SetupDatabase] Schema ${schema} on ${connection.host}:${connection.port} was created `
+      + `with collation ${present}, and this service declares ${collation} - refusing to build.\n`
+      + '       A CREATE DATABASE IF NOT EXISTS over an existing database changes nothing and reports '
+      + 'success, so the run would prove a schema it never built.\n'
+      + `       Fix: create the database with the declared collation — in CI give the database service `
+      + `MARIADB_COLLATION=${collation} beside MARIADB_DATABASE (or drop MARIADB_DATABASE and let this `
+      + `gate create it); on an existing instance, ALTER DATABASE \`${schema}\` COLLATE ${collation}. `
+      + 'The key itself is api/docs/biz/70-contracts/database-contract.md §1.');
+  }
+
+  const created = exec({ connection, sql: createDatabaseSql(schema, collation) });
+  if (created.status !== 0) {
+    throw new Error(`[SetupDatabase] Could not create schema ${schema}:\n${created.stderr}`);
+  }
+}
+
 /**
  * Build the schema from the declared migrations.
  *
@@ -125,12 +294,11 @@ function buildSchema({ serviceRoot, database, connection, exec = defaultExec })
   const port = connection.port ?? 3306;
 
   const conn = { ...connection, port };
+  const collation = requireCollation(database);
   const plan = resolveMigrationPlan(serviceRoot, database);
 
-  const created = exec({ connection: conn, sql: `CREATE DATABASE IF NOT EXISTS \`${database.schema}\`;` });
-  if (created.status !== 0) {
-    throw new Error(`[SetupDatabase] Could not create schema ${database.schema}:\n${created.stderr}`);
-  }
+  assertTargetIsEmpty({ exec, connection: conn, schema: database.schema });
+  createSchema({ exec, connection: conn, schema: database.schema, collation });
 
   const apply = (file, kind) => {
     const result = exec({ connection: conn, schema: database.schema, file });
@@ -151,4 +319,17 @@ function buildSchema({ serviceRoot, database, connection, exec = defaultExec })
   };
 }
 
-module.exports = { resolveMigrationPlan, buildSchema };
+// `requireCollation`, `createDatabaseSql` and `defaultExec` are exported for
+// `throwawaySchema.js`, the build an integration test uses. The two builds
+// differ in exactly one decision — the CI gate refuses a target it did not
+// create, the test one drops and recreates its own — and in nothing else: the
+// migration set and its order, the collation requirement, the CREATE statement
+// and the client invocation have one definition each, here
+// (`change-discipline.md` § One rail per concern).
+module.exports = {
+  resolveMigrationPlan,
+  buildSchema,
+  requireCollation,
+  createDatabaseSql,
+  defaultExec
+};